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 at concat_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 the output_path with no prompt. If False, the function will fail if the output_path exists. Defaults to None (prompts user for input). You must specify a value if you have suppressed terminal output with autoscrub.suppress_ffmpeg_output()

Returns:

output_path if successful or None.

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 the output_path with no prompt. If False, the function will fail if the output_path exists. Defaults to None (prompts user for input). You must specify a value if you have suppressed terminal output with autoscrub.suppress_ffmpeg_output()
Returns:

The output_path where the output of ffmpeg was written.

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 unless output_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 the output_path with no prompt. If False, the function will fail if the output_path exists. Defaults to None (prompts user for input). You must specify a value if you have suppressed terminal output with autoscrub.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 the output_path with no prompt. If False, the function will fail if the output_path exists. Defaults to None (prompts user for input). You must specify a value if you have suppressed terminal output with autoscrub.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() and panGainAudioGraph() 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.

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 the output_path with no prompt. If False, the function will fail if the output_path exists. Defaults to None (prompts user for input). You must specify a value if you have suppressed terminal output with autoscrub.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.

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.

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 with False 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 the output_path with no prompt. If False, the function will fail if the output_path exists. Defaults to None (prompts user for input). You must specify a value if you have suppressed terminal output with autoscrub.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. See trim() for the supported formats of tstart and tstop.
  • 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 that tstart, tstop and output_path cannot be specified as additional keyword arguments as they are already specified explicitly when trimSegments calls trim.
Returns:

A list of paths to each segment created.

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