storyboard.metadata module

Extract video metadata with FFprobe.

Classes

Stream()	Container for stream metadata.
Video(video[, params])	Container for video and streams metadata.

Routines

main()

CLI interface.

---

class storyboard.metadata.Stream

Bases: object

Container for stream metadata.

Some of the documented attributes are optional; in particular, some attributes are video stream specific. (In that case of an unavailable attribute, the value will be None)

Attributes

index	(int) Stream index within the video container.
type	(str) 'video', 'audio', 'subtitle', 'data', etc.
codec	(str) (Long) name of codec.
bit_rate	(float) Bit rate of stream, in bit per second.
bit_rate_text	(str) Bit rate as a human readable string, e.g., '360 kb/s'.
language_code	(str)
width	(int)
height	(int)
dimension	(tuple) (width, height), e.g., (1920, 1080).
dimension_text	(str) Dimension as a human readable string, e.g. '1920x1080'.
frame_rate	(float) Frame rate of video stream, in frames per second (fps).
frame_rate_text	(str) Frame rate as a human readable string, e.g., '24 fps'.
dar	(float) Display aspect ratio.
dar_text	(str) Display aspect ratio as a human readable string, e.g., '16:9'.
sample_rate	(float) Sample rate of audio stream, in Hz.
sample_rate_text	(str) Sample rate as a human readable string, e.g., '44100 Hz'.
channel_layout	(str) Channel layout of audio stream, e.g. 'stereo'.
info_string	(str) Assembled string of stream metadata, intended for printing.

class storyboard.metadata.Video(video, params=None)

Bases: object

Container for video and streams metadata.

A Video object holds video metadata (including container metadata and per-stream metadata), and generates a formatted string for printing upon request (the format_metadata method).

Some of the documented attributes might not be available for certain video files (in that case the value will be None).

Parameters:

video : str

Path to the video file.

params : dict, optional

Optional parameters enclosed in a dict. Default is None. See the “Other Parameters” section for understood key/value pairs.

Other Parameters:  

ffprobe_bin : str, optional

Name/path of the ffprobe binary (should be callable). By default the name is guessed based on OS type. (See the storyboard.fflocate module.)

video_duration : float, optional

Duration of the video in seconds. If None, extract the duration from container metadata. Default is None. This is only needed in edge cases where the duration of the video cannot be read off from container metadata, or the duration extracted is wrong. See #3 for details.

print_progress : bool, optional

Whether to print progress information (to stderr). Default is False.

debug : bool, optional

Print extra debug information. Default is False.

Raises:

OSError

If fails to extract metadata with ffprobe, e.g., if the file is not present, or in a format that is not recognized by ffprobe, or if ffprobe cannot be called, etc.

Notes

The unmodified JSON output of ffprobe -show_format -show_streams on the video is saved in a private instance attribute _ffprobe.

Attributes

format	(str) (Long) name of container format.
title	(str)
size	(int) Size of video file in bytes.
size_text	(str) Size as a human readable string, e.g., '128MiB'.
duration	(float) Duration of video in seconds.
duration_text	(str) Duration as a human readable string, e.g., '00:02:53.33'.
scan_type	(str) 'Progressive scan', 'Interlaced scan', or 'Telecined video'.
dimension	((width, height)) E.g., (1920, 1080).
dimension_text	(str) Dimension as a human readable string, e.g. '1920x1080'.
sha1sum	(str) The SHA-1 hex digest of the video file (40 character hexadecimal string). Since computing SHA-1 digest is an expensive operation, this attribute is only calculated and set upon request, either through compute_sha1sum or format_metadata with the include_sha1sum optional parameter set to True.
frame_rate	(float) Frame rate of video stream, in frames per second (fps).
frame_rate_text	(str) Frame rate as a human readable string, e.g., '24 fps'.
bit_rate	(float) Bit rate of video, in bit per second.
bit_rate_text	(str) Bit rate as a human readable string, e.g., '2000 kb/s'.
dar	(float) Display aspect ratio.
dar_text	(str) Display aspect ratio as a human readable string, e.g., '16:9'.
streams	(list) A list of Stream objects, containing per-stream metadata.

compute_sha1sum(params=None)

Computes the SHA-1 digest of the video file.

Parameters:

params : dict, optional

Optional parameters enclosed in a dict. Default is None. See the “Other Parameters” section for understood key/value pairs.

Returns:

sha1sum : str

The SHA-1 hex digest of the video file (40 character hexadecimal string).

Other Parameters:  

print_progress : bool, optional

Whether to print progress information (to stderr). Default is False.

Notes

Since computing SHA-1 digest is an expensive operation, the digest is only calculated and set upon request, either through this method or format_metadata with the include_sha1sum optional parameter set to True. Further requests load the calculated value rather than repeat the computation.

format_metadata(params=None)

Return video metadata in one formatted string.

Parameters:

params : dict, optional

Optional parameters enclosed in a dict. Default is None. See the “Other Parameters” section for understood key/value pairs.

Returns:

str

A formatted string loaded with video and per-stream metadata, which can be printed directly. See the “Examples” section for a printed example.

Other Parameters:  

include_sha1sum : bool, optional

Whether to include the SHA-1 hex digest. Default is False. Keep in mind that computing SHA-1 digest is an expensive operation, and hence is only performed upon request.

print_progress : bool, optional

Whether to print progress information (to stderr). Default is False.

Examples

>>> import os
>>> import tempfile
>>> try:
...     from urllib.request import urlretrieve
... except ImportError:
...     from urllib import urlretrieve
>>> video_uri = 'https://dl.bintray.com/zmwangx/pypi/sample-h264-aac-srt.mkv'
>>> tempdir = tempfile.mkdtemp()
>>> video_file = os.path.join(tempdir, 'sample-h264-aac-srt.mkv')
>>> _ = urlretrieve(video_uri, filename=video_file)
>>> print(Video(video_file).format_metadata({'include_sha1sum': True}))
Title:                  Example video: H.264 + AAC + SRT in Matroska container
Filename:               sample-h264-aac-srt.mkv
File size:              4842 (4.73KiB)
SHA-1 digest:           95E7D9F9359D8D7BA4EC441BC8CB3830A58EE102
Container format:       Matroska
Duration:               00:00:02.08
Pixel dimensions:       128x72
Display aspect ratio:   16:9
Scan type:              Progressive scan
Frame rate:             25 fps
Bit rate:               19 kb/s
Streams:
    #0: Video, H.264 (High Profile level 1.0), 128x72 (DAR 16:9), 25 fps
    #1: Audio (und), AAC (Low-Complexity), 44100 Hz, mono
    #2: Subtitle, SubRip
>>> os.remove(video_file)
>>> os.rmdir(tempdir)

storyboard.metadata.main()

CLI interface.