storyboard.storyboard module¶
Generate video storyboards with metadata reports.
Classes¶
| Font([font_file, font_size]) | Wrapper for a font loaded by PIL.ImageFont. |
| StoryBoard(video[, params]) | Class for creating video storyboard. |
Routines¶
| create_thumbnail(frame, width[, params]) | Create thumbnail of a video frame. |
| draw_text_block(canvas, xy, text[, params]) | Draw a block of text. |
| tile_images(images, tile[, params]) | Combine images into a composite image through 2D tiling. |
| main() | CLI interface. |
- class storyboard.storyboard.Font(font_file=None, font_size=None)[source]¶
Bases: builtins.object
Wrapper for a font loaded by PIL.ImageFont.
Parameters: font_file : str
Path to the font file to be loaded. If None, load the default font defined by the module variable DEFAULT_FONT_FILE. Default is None. Note that the font must be supported by FreeType.
font_size : int
Font size to be loaded. If None, use the default font size defined by the module variable DEFAULT_FONT_SIZE. Default is None.
Raises: OSError
If the font cannot be loaded (by PIL.ImageFont.truetype).
Notes
We are creating this wrapper because there’s no guarantee that a font loaded by Pillow will have the .size property, and sometimes it certainly doesn’t (try PIL.ImageFont.load_default(), for instance). The font size, however, is crucial for some of other drawings, so we would like to keep it around all the time.
Attributes
obj A Pillow font object, e.g., of the type PIL.ImageFont.FreeTypeFont. size (int) The font size.
- class storyboard.storyboard.StoryBoard(video, params=None)[source]¶
Bases: builtins.object
Class for creating video storyboard.
Parameters: video
Either a string specifying the path to the video file, or a storyboard.metadata.Video object.
params : dict, optional
Optional parameters enclosed in a dict. Default is None. See the “Other Parameters” section for understood key/value pairs.
Other Parameters: bins : tuple, optional
A tuple (ffmpeg_bin, ffprobe_bin), specifying the name of path of FFmpeg and FFprobe’s binaries on your system. If None, the bins are guessed according to type of OS, using storyboard.fflocate.guess_bins (e.g., on OS X and Linux systems, the natural names are 'ffmpeg' and 'ffprobe'; on Windows, the names have '.exe' suffixes). Default is None.
frame_codec : str, optional
Image codec to use when extracting frames using FFmpeg. Default is 'png'. Use this option with caution only if your FFmpeg cannot encode PNG, which is unlikely.
video_duration : float, optional
Duration of the video in seconds, passed to the storyboard.metadata.Video constructor. If None, extract the duration from video container metadata. Default is None. You should rarely need this option, unless the duration of the video cannot be extracted from video container metadata, or the duration extracted is wrong. Either case is fatal to the storyboard (since the frames extracted depend on the duration), and this option provides a fallback. See #3 for details.
print_progress : bool, optional
Whether to print progress information (to stderr). Default is False.
Raises: OSError
If ffmpeg and ffprobe binaries do not exist or seem corrupted, or if the video does not exist or cannot be recognized by FFprobe.
Notes
For developers: there are two private attributes. _bins is a tuple of two strs holding the name or path of the ffmpeg and ffprobe binaries; _frame_codec is a str holding the image codec used by FFmpeg when generating frames (usually no one needs to touch this).
Attributes
video (storyboard.metadata.Video) frames (list) List of equally spaced frames in the video, as storyboard.frame.Frame objects. The list is empty after __init__. See the gen_frames method. - gen_frames(count, params=None)[source]¶
Extract equally spaced frames from the video.
When tasked with extracting N frames, this method extracts them at positions 1/2N, 3/2N, 5/2N, ... , (2N-1)/2N of the video. The extracted frames are stored in the frames attribute.
Note that new frames are extracted only if the number of existing frames in the frames attribute doesn’t match the specified count (0 at instantiation), in which case new frames are extracted to match the specification, and the frames attribute is overwritten.
Parameters: count : int
Number of (equally-spaced) frames to generate.
params : dict, optional
Optional parameters enclosed in a dict. Default is None. See the “Other Parameters” section for understood key/value pairs.
Returns: None
Access the generated frames through the frames attribute.
Other Parameters: print_progress : bool, optional
Whether to print progress information (to stderr). Default is False.
Raises: OSError
If frame extraction with FFmpeg fails.
- gen_storyboard(params=None)[source]¶
Generate full storyboard.
A full storyboard has three sections, arranged vertically in the order listed: a metadata sheet, a bare storyboard, and a promotional banner.
The metadata sheet consists of formatted metadata generated by storyboard.metadata.Video.format_metadata; you may choose whether to include the SHA-1 hex digest of the video file (see include_sha1sum in “Other Parameters”). The bare storyboard is an array (usually 4x4) of thumbnails, generated from equally spaced frames from the video. The promotional banner briefly promotes this package (storyboard).
The metadata sheet and promotional banner are optional and can be turned off individually. See include_metadata_sheet and include_promotional_banner in “Other Parameters”.
Here is a basic example of a full storyboard.
Parameters: params : dict, optional
Optional parameters enclosed in a dict. Default is None. See the “Other Parameters” section for understood key/value pairs.
Returns: full_storyboard : PIL.Image.Image
Other Parameters: include_metadata_sheet: bool, optional
Whether to include a video metadata sheet in the storyboard. Default is True.
include_promotional_banner: bool, optional
Whether to include a short promotional banner about this package (storyboard) at the bottom of the storyboard. Default is True.
background_color : color, optional
Background color of the storyboard, in any color format recognized by Pillow. Default is 'white'.
section_spacing : int, optional
Vertical spacing between adjacent sections (metadata sheet and bare storyboard, bare storyboard and promotional banner). If None, use the vertical tile spacing (see tile_spacing). Default is None.
margins : tuple, optional
A tuple (hor, ver) specifying the horizontal and vertical margins (padding) around the entire storyboard (all sections included). Default is (10, 10).
tile : tuple, optional
A tuple (cols, rows) specifying the number of columns and rows for the array of thumbnails in the storyboard. Default is (4, 4).
tile_spacing : tuple, optional
A tuple (hor, ver) specifying the horizontal and vertical spacing between adjacent thumbnails. Default is (8, 6).
thumbnail_width : int, optional
Width of each thumbnail. Default is 480 (as in 480x270 for a 16:9 video).
thumbnail_aspect_ratio : float, optional
Aspect ratio of generated thumbnails. If None, first try to use the display aspect ratio of the video (self.video.dar), then the aspect ratio of the frames if self.video.dar is not available. Default is None.
draw_timestamp : bool, optional
Whether to draw frame timestamps on top of thumbnails (as an overlay). Default is True.
timestamp_font : Font, optional
Font used for timestamps, if draw_timestamp is True. Default is the font constructed by Font() without arguments.
timestamp_align : {‘right’, ‘center’, ‘left’}, optional
Horizontal alignment of timestamps over the thumbnails, if draw_timestamp is True. Default is 'right'. Note that timestamps are always vertically aligned to the bottom.
text_font: Font, optional
Font used for metadata sheet and promotional banner. Default is the font constructed by Font() without arguments.
text_color: color, optional
Color of metadata and promotional text, in any format recognized by Pillow. Default is 'black'.
line_spacing: float, optional
Line spacing of metadata text as a float, e.g., 1.0 for single spacing, 1.5 for one-and-a-half spacing, and 2.0 for double spacing. Default is 1.2.
include_sha1sum: bool, optional
Whether to include the SHA-1 hex digest of the video file in the metadata fields. Default is False. Be aware that computing SHA-1 digest is an expensive operation.
print_progress : bool, optional
Whether to print progress information (to stderr). Default is False.
- storyboard.storyboard.create_thumbnail(frame, width, params=None)[source]¶
Create thumbnail of a video frame.
The timestamp of the frame can be overlayed to the thumbnail. See “Other Parameters” to how to enable this feature and relevant options.
Parameters: frame : storyboard.frame.Frame
The video frame to be thumbnailed.
width : int
Width of the thumbnail.
params : dict, optional
Optional parameters enclosed in a dict. Default is None. See the “Other Parameters” section for understood key/value pairs.
Returns: thumbnail : PIL.Image.Image
Other Parameters: aspect_ratio : float, optional
Aspect ratio of the thumbnail. If None, use the aspect ratio (only considering the pixel dimensions) of the frame. Default is None.
draw_timestamp : bool, optional
Whether to draw frame timestamp over the timestamp. Default is False.
timestamp_font : Font, optional
Font for the timestamp, if draw_timestamp is True. Default is the font constructed by Font() without arguments.
timestamp_align : {‘right’, ‘center’, ‘left’}, optional
Horizontal alignment of the timestamp over the thumbnail, if draw_timestamp is True. Default is 'right'. Note that the timestamp is always vertically aligned towards the bottom of the thumbnail.
- storyboard.storyboard.draw_text_block(canvas, xy, text, params=None)[source]¶
Draw a block of text.
You need to specify a canvas to draw upon. If you are not sure about the size of the canvas, there is a dry_run option (see “Other Parameters” that help determine the size of the text block before creating the canvas.
Parameters: canvas : PIL.ImageDraw.Image
The canvas to draw the text block upon. If the dry_run option is on (see “Other Parameters”), canvas can be None.
xy : tuple
Tuple (x, y) consisting of x and y coordinates of the topleft corner of the text block.
text : str
Text to be drawn, can be multiline.
params : dict, optional
Optional parameters enclosed in a dict. Default is None. See the “Other Parameters” section for understood key/value pairs.
Returns: (width, height)
Size of text block.
Other Parameters: font : Font, optional
Default is the font constructed by Font() without arguments.
color : color, optional
Color of text; can be in any color format accepted by Pillow (used for the fill argument of PIL.ImageDraw.Draw.text). Default is 'black'.
spacing : float, optional
Line spacing as a float. Default is 1.2.
dry_run : bool, optional
If True, do not draw anything, only return the size of the text block. Default is False.
- storyboard.storyboard.tile_images(images, tile, params=None)[source]¶
Combine images into a composite image through 2D tiling.
For example, 16 thumbnails can be combined into an 4x4 array. As another example, three images of the same width (think of the metadata sheet, the bare storyboard, and the promotional banner) can be combined into a 1x3 array, i.e., assembled vertically.
The image list is processed column-first.
Note that except if you use the tile_size option (see “Other Parameters”), you should make sure that images passed into this function satisfy the condition that the widths of all images in each column and the heights of all images in each row match perfectly; otherwise, this function will give up and raise a ValueError.
Parameters: images : list
A list of PIL.Image.Image objects, satisfying the necessary height and width conditions (see explanation above).
tile : tuple
A tuple (m, n) indicating m columns and n rows. The product of m and n should be the length of images, or a ValueError will arise.
params : dict, optional
Optional parameters enclosed in a dict. Default is None. See the “Other Parameters” section for understood key/value pairs.
Returns: PIL.Image.Image
The composite image.
Other Parameters: tile_size : tuple, optional
A tuple (width, height). If this parameter is specified, width and height consistency conditions won’t be checked, and every image will be resized to (width, height) when combined. Default is None.
tile_spacing : tuple, optional
A tuple (hor, ver) specifying the horizontal and vertical spacing between adjacent tiles. Default is (0, 0).
margins : tuple, optional
A tuple (hor, ver) specifying the horizontal and vertical margins (padding) around the combined image. Default is (0, 0).
canvas_color : color, optional
A color in any format recognized by Pillow. This is only relevant if you have nonzero tile spacing or margins, when the background shines through the spacing or margins. Default is 'white'.
close_separate_images : bool
Whether to close the separate after combining. Closing the images will release the corresponding resources. Default is False.
Raises: ValueError
If the length of images does not match the product of columns and rows (as defined in tile), or the widths and heights of the images do not satisfy the necessary consistency conditions.