autoscrub API¶
Advanced users may wish to build their own Python programs that use the autoscrub API. To use the autoscrub API, include import autoscrub
at the top of your Python file and call the below functions as required.
-
autoscrub.
concatFileList
(concat_path, output_path, overwrite=None)[source]¶ Take a file list for the ffmpeg concat demuxer and save to
output_path
. The concat file (located atconcat_path
) must contain lines of the form:file '/path/to/file1' file '/path/to/file2' file '/path/to/file3'
This avoids a re-encode and can be used with formats that do not support file level concatenation.
Parameters: - concat_path – the filepath containing the list of media files to concatenate
- output_path – the filepath at which to write the result of the concatenation
Keyword Arguments: overwrite – If
True
, overwrites theoutput_path
with no prompt. IfFalse
, the function will fail if theoutput_path
exists. Defaults toNone
(prompts user for input). You must specify a value if you have suppressed terminal output withautoscrub.suppress_ffmpeg_output()
Returns: output_path
if successful orNone
.
-
autoscrub.
concatSegments
(segment_paths, output_path=None, overwrite=None)[source]¶ Concatenate a list of inputs (
segment_paths
) using the ffmpeg concat demuxer. A concat file will be created of the form:file '/path/to/file1' file '/path/to/file2' file '/path/to/file3'
This avoids a re-encode and can be used with formats that do not support file level concatenation.
Parameters: segment_paths – A list of filepaths to concatenate
Keyword Arguments: - output_path – the filepath at which to write the concat file. If left
as the default (
None
) it appends_concat
to the end of the filename and preserves the input file extension. - overwrite – If
True
, overwrites theoutput_path
with no prompt. IfFalse
, the function will fail if theoutput_path
exists. Defaults toNone
(prompts user for input). You must specify a value if you have suppressed terminal output withautoscrub.suppress_ffmpeg_output()
Returns: The
output_path
where the output of ffmpeg was written.- output_path – the filepath at which to write the concat file. If left
as the default (
-
autoscrub.
ffmpeg
(filename, args=[], output_path=None, output_type=None, overwrite=None)[source]¶ Runs ffmpeg on filename with the specified args.
Parameters: filename – The filepath passed to the
-i
option of ffmpeg.Keyword Arguments: - args – A list of additional arguments to pass to ffmpeg.
- output_path – The filepath to append to the end of the ffmpeg command,
designating the output file for the ffmpeg result. If left
as the default (
None
) it appends_processed
to the end of the filename and preserves input file extension unlessoutput_type
is specified. - output_type – Determines the output file type. Specify as a string
containing the required file extension. This is ignored if
output_path
is specified. - overwrite – If
True
, overwrites theoutput_path
with no prompt. IfFalse
, the function will fail if theoutput_path
exists. Defaults toNone
(prompts user for input). You must specify a value if you have suppressed terminal output withautoscrub.suppress_ffmpeg_output()
Returns: The
output_path
where the output of ffmpeg was written.
-
autoscrub.
ffmpegComplexFilter
(input_path, filter_script_path, output_path='/dev/null', run_command=True, overwrite=None, stderr_callback=None)[source]¶ Executes the ffmpeg command and processes a complex filter
Prepare and execute (if run_command) ffmpeg command for processing input_path with an ffmpeg filter_complex string (filtergraph) in filter_script_path, and save to output_path. As this requires re-encoding, video and audio settings are chosen to be compliant with YouTube’s ‘streamable content’ specifications, available at (as of April 2017) https://support.google.com/youtube/answer/1722171
Parameters: - input_path – The path to the video file to process.
- filter_script_path – The path to the filter script.
Keyword Arguments: - output_path – The path to save the processed video (defaults to os.devnull).
- run_command – If False, simply prepare and return the command for debugging or later use (default: True).
- overwrite – If
True
, overwrites theoutput_path
with no prompt. IfFalse
, the function will fail if theoutput_path
exists. Defaults toNone
(prompts user for input). You must specify a value if you have suppressed terminal output withautoscrub.suppress_ffmpeg_output()
- stderr_callback – A reference to a python function to be called when a new line is printed to stderr by ffmpeg. Useful for monitoring the progress of ffmpeg in realtime. Defaults to None.
Returns: the FFmpeg command sequence as a list (to be passed to
subprocess.Popen
or formatted into a string for printing).
-
autoscrub.
ffprobe
(filename)[source]¶ Runs ffprobe on
filename
and returns the log output from stderr.Parameters: filename – The filepath passed to ffprobe. Returns: The output of the ffprobe command.
-
autoscrub.
findDuration
(log_output)[source]¶ Finds the duration in seconds from ffprobe log_output.
Parameters: log_output – The output of ffprobe, as returned by autoscrub.ffprobe()
.Returns: A float containing duration in seconds or None if the duration could not be determined.
-
autoscrub.
findLoudness
(log_output)[source]¶ Extract loudness (key, value) pairs from ffmpeg log_output when using the ebur128 filter.
Parameters: log_output – The output of the ffmpeg ebur128 filter, as returned by autoscrub.getLoudness()
.Returns: A loudness dictionary with keys: I: integrated loudness in dBLUFS LRA: loudness range in dBLUFS LRA high: LRA low: Threshold:
-
autoscrub.
findSampleRate
(log_output)[source]¶ Finds the audio sample rate in Hz from ffprobe log_output.
Parameters: log_output – The output of ffprobe, as returned by autoscrub.ffprobe()
.Returns: A float containing audio sample rate in Hz or None if the sample rate could not be determined.
-
autoscrub.
findSilences
(log_output)[source]¶ Extract silences from ffmpeg log_output when using the silencedetect filter.
Parameters: log_output – The output of the ffmpeg silencedetect filter, as returned by autoscrub.getSilences()
.Returns: a list of silence dictionaries, with keys: silence_start: the timestamp of the detected silent interval in seconds silence_end: the timestamp of the detected silent interval in seconds silence_duration: duration of the silent interval in seconds
-
autoscrub.
generateFilterGraph
(silences, factor, delay=0.25, rescale=True, pan_audio='left', gain=0, audio_rate=44100, hasten_audio=None, silent_volume=1.0)[source]¶ Generate a filtergraph string (for processing with the -filter_complex flag of ffmpeg) using the trim and atrim filters to speed up periods in the video designated by a list of silence dictionaries. This function calls
autoscrub.silenceFilterGraph()
,autoscrub.resizeFilterGraph()
andpanGainAudioGraph()
as appropriate.Parameters: - silences – A list of silence dictionaries generated from
autoscrub.getSilences()
- factor – to speed up video during (a subset of) each silent interval
Keyword Arguments: - delay – to omit from silent intervals when changing speed (default 0.25s)
- rescale – Scale and pad the video (pillar- or letter-box as required) for 1920 x 1080 display (default True)
- pan_audio – ‘left’, ‘right’, or None/False specify whether to duplicate a stereo channel of input audio stream (default ‘left’)
- gain – in dB to apply when pan_audio is ‘left’ or ‘right’
- audio_rate – Sample rate of audio input (in Hz, default 44100) used in
asetrate/aresample filters when
hasten_audio=True
. - hasten_audio – None, ‘pitch’ or ‘tempo’. Speed up audio during silent segment by either increasing pitch (with asetrate and aresample filters) or tempo (with atempo filter).
- silent_volume – scale the volume during silent segments (default 1.0; no scaling).
Returns: The generated filtergraph as a string.
- silences – A list of silence dictionaries generated from
-
autoscrub.
getDuration
(filename)[source]¶ Runs ffprobe on filename and extracts duration in seconds.
Parameters: filename – The filepath of the media file you wish to process. Returns: A float containing duration in seconds or None if the duration could not be determined.
-
autoscrub.
getLoudness
(filename)[source]¶ Runs the ffmpeg ebur128 filter on filename.
Parameters: filename – the path to the video file to examine. Returns: A loudness dictionary with keys: I: integrated loudness in dBLUFS LRA: loudness range in dBLUFS LRA high: LRA low: Threshold:
-
autoscrub.
getSampleRate
(filename)[source]¶ Runs ffprobe on filename and extracts audio sample rate in Hz.
Parameters: filename – The filepath of the media file you wish to process. Returns: A float containing audio sample rate in Hz or None if the sample rate could not be determined.
-
autoscrub.
getSilences
(filename, input_threshold_dB=-18.0, silence_duration=2.0, save_silences=True)[source]¶ Runs the ffmpeg filter silencedetect with the specified settings.
Parameters: filename – the path to the video file to examine
Keyword Arguments: - input_threshold – instantaneous level (in dB) to detect silences with (default -18).
- silence_duration – seconds for which level mustn’t exceed threshold to declare silence (default 2).
- save_silences – print the above timestamps to CSV file (default = True).
Returns: a list of silence dictionaries, with keys:
silence_start: the timestamp of the detected silent interval in seconds silence_end: the timestamp of the detected silent interval in seconds silence_duration: duration of the silent interval in seconds
-
autoscrub.
hhmmssd_to_seconds
(s)[source]¶ Convert a
'[hh:]mm:ss[.d]'
string to seconds.The reverse of
autoscrub.seconds_to_hhmmssd()
Parameters: s – A string in the format '[hh:]mm:ss[.d]'
. The hours and decimal seconds are optional.Returns: The number of seconds as a float.
-
autoscrub.
matchLoudness
(filename, target_lufs=-18, output_path=None, overwrite=None)[source]¶ Applies the volume ffmpeg filter in an attempt to change the audio volume to match the specified target.
Parameters: filename – the path to the video file to examine.
Keyword Arguments: - target_lufs – The target LUFS for the output audio (default: -18)
- output_path – the filepath at which to write the resultant file. If no
output path is specified, it follows the conventions of
autoscrub.ffmpeg()
. - overwrite – If
True
, overwrites theoutput_path
with no prompt. IfFalse
, the function will fail if theoutput_path
exists. Defaults toNone
(prompts user for input). You must specify a value if you have suppressed terminal output withautoscrub.suppress_ffmpeg_output()
Returns: The
output_path
where the output of ffmpeg was written.
-
autoscrub.
panGainAudioGraph
(a_in='[0:a]', duplicate_ch='left', gain=0, a_out='[a]')[source]¶ Generate a filtergraph string (for processing with the -filter_complex flag of ffmpeg) using the pan and volume filters to duplicate audio from one stereo channel to another, and optionally change the volume by gain.
Keyword Arguments: - a_in – The named filtergraph audio input pad. Defaults to
[0:a]
(see FFmpeg filter documentation). - duplicate_ch – ‘left’, ‘right’, or None/False specify whether to duplicate a stereo channel of input audio stream (default ‘left’).
- gain – to apply (in dB) to the audio stream using the volume filter.
- a_out – The named filtergraph audio output pad. Defaults to
[a]
(see FFmpeg filter documentation).
Returns: The generated filtergraph as a string.
- a_in – The named filtergraph audio input pad. Defaults to
-
autoscrub.
resizeFilterGraph
(v_in='[0:v]', width=1920, height=1080, pad=True, mode='decrease', v_out='[v]')[source]¶ Generate a filtergraph string (for processing with the -filter_complex flag of ffmpeg) using the scale and pad filters to scale & pad the video for width x height display, with optional padding.
Keyword Arguments: - v_in – The named filtergraph video input pad. Defaults to
[0:v]
(see FFmpeg filter documentation). - width – of display on which the output stream must fit (default 1920).
- height – of display on which the output stream must fit (default 1080).
- pad – add letter- or pillar-boxes to the output as required to fill width x height.
- mode – argument of ffmpeg scale filter (default ‘decrease’).
- v_out – The named filtergraph video output pad. Defaults to
[v]
(see FFmpeg filter documentation).
Returns: The generated filtergraph as a string.
- v_in – The named filtergraph video input pad. Defaults to
-
autoscrub.
seconds_to_hhmmssd
(t, decimal=True)[source]¶ Convert a float (in seconds) to a
'[hh:]mm:ss[.d]'
formatted string.The reverse of
autoscrub.hhmmssd_to_seconds()
Parameters: t – The number of seconds as a float Keyword Arguments: decimal – Whether to include the decimal component (default: True) Returns: The number of seconds as a '[hh:]mm:ss[.d]'
formatted string.
-
autoscrub.
set_terminal_encoding
(encoding)[source]¶ Sets the encoding used for communicating with ffmpeg and ffprobe
Sets the default value used to decode strings returned from
subprocess.Popen
. This should match your system encoding, and is unlikely to need changing.
-
autoscrub.
silenceFilterGraph
(silences, factor, delay=0.25, audio_rate=44100, hasten_audio=None, silent_volume=1.0, v_in='[0:v]', a_in='[0:a]', v_out='[v]', a_out='[a]')[source]¶ Generate a filtergraph string (for processing with the -filter_complex flag of ffmpeg) using the trim and atrim filters to speed up periods in the video designated by a list of silence dictionaries, where each silence dictionary contains keys:
silence_start: the timestamp of the detected silent interval in seconds silence_end: the timestamp of the detected silent interval in seconds silence_duration: duration of the silent interval in seconds
Parameters: - silences – A list of silence dictionaries generated from getSilences
- factor – to speed up video during (a subset of) each silent interval
Keyword Arguments: - delay – to omit from silent intervals when changing speed (default 0.25s)
- audio_rate – Sample rate of audio input (in Hz, default 44100) used in asetrate/aresample filters when hasten_audio=True
- hasten_audio – None, ‘pitch’ or ‘tempo’. Speed up audio during silent segment by either increasing pitch (with asetrate and aresample filters) or tempo (with atempo filter).
- silent_volume – scale the volume during silent segments (default 1.0; no scaling)
- v_in – The named filtergraph video input pad. Defaults to
[0:v]
(see the FFmpeg filter documentation). - a_in – The named filtergraph audio input pad. Defaults to
[0:a]
(see the FFmpeg filter documentation). - v_out – The named filtergraph video output pad. Defaults to
[v]
(see the FFmpeg filter documentation). - a_out – The named filtergraph audio output pad. Defaults to
[a]
(see the FFmpeg filter documentation).
Returns: The generated filtergraph as a string
-
autoscrub.
suppress_ffmpeg_output
(suppress)[source]¶ suppresses the output to the terminal from FFmpeg and FFprobe.
Output is printed by default unless this function is called with the argument
True
. Call withFalse
to enable terminal output again.Parameters: suppress – If True
, ffmpeg and ffprobe output will be suppressed.
-
autoscrub.
trim
(input_path, tstart=0, tstop=None, output_path=None, overwrite=None, codec='copy', output_type=None)[source]¶ Extract contents of input_path between tstart and tstop.
Parameters: input_path – The path to the media file to process
Keyword Arguments: - tstart – A integer/float in seconds, or a ‘[hh:]mm:ss[.d]’ string (default 0)
- tstop – A integer/float in seconds, or a ‘[hh:]mm:ss[.d]’ string (default None)
- output_path – Defaults to appending ‘_trimmed’ to input_path
- overwrite – If
True
, overwrites theoutput_path
with no prompt. IfFalse
, the function will fail if theoutput_path
exists. Defaults toNone
(prompts user for input). You must specify a value if you have suppressed terminal output withautoscrub.suppress_ffmpeg_output()
- codec – Specify the codec to use in the encoding of the output file (default: copy).
- output_type – Determines the output file type. Specify as a string
containing the required file extension. This is ignored if
output_path
is specified.
Returns: The
output_path
where the output of ffmpeg was written.
-
autoscrub.
trimSegments
(input_path, trimpts, output_path=None, output_type=None, **kwargs)[source]¶ Extract segments of a file using a list of
(tstart, tstop)
tuples. Each segment is saved as a file of the same type as the original.Parameters: input_path – The path to the media file to process
Keyword Arguments: - trimpts – A list of
(tstart, tstop)
tuples. Seetrim()
for the supported formats oftstart
andtstop
. - output_path – The folder in which to save the segments. Defaults to the folder ‘temp’ in the current working directory.
- output_type – Determines the output file type. Specify as a string containing the required file extension.
- kwargs – A list of additional keyword arguments to pass to
trim()
. Note thattstart
,tstop
andoutput_path
cannot be specified as additional keyword arguments as they are already specified explicitly whentrimSegments
callstrim
.
Returns: A list of paths to each segment created.
- trimpts – A list of
-
autoscrub.
writeFilterGraph
(filter_script_path, silences, factor, **kwargs)[source]¶ Generates a filtergraph string (using
autoscrub.generateFilterGraph()
) and writes it to a file.Parameters: - filter_script_path – Path to save the filter script .
- silences – A list of silence dictionaries generated from
autoscrub.getSilences()
. - factor – to speed up video during (a subset of) each silent interval.
Keyword Arguments: kwargs – Accepts keyword arguments of
autoscrub.generateFilterGraph()
.Returns: None