acsuite documentation

Frame-based cutting/trimming/splicing of audio with VapourSynth and FFmpeg.

acsuite.eztrim(clip, trims, audio_file, outfile=None, *, ffmpeg_path=None, quiet=False, timecodes_file=None, debug=False)[source]

Simple trimming function that follows VapourSynth/Python slicing syntax.

End frame is NOT inclusive.

For a 100 frame long VapourSynth clip:

>>> src = core.ffms2.Source('file.mkv')
>>> clip = src[3:22]+src[23:40]+src[48]+src[50:-20]+src[-10:-5]+src[97:]
>>> 'These trims can be almost directly entered as:'
>>> trims = [(3, 22), (23, 40), (48, 49), (50, -20), (-10, -5), (97, None)]
>>> eztrim(src, trims, 'audio_file.wav')
>>> src = core.ffms2.Source('file.mkv')
>>> clip = src[3:-13]
>>> 'A single slice can be entered as a single tuple:'
>>> eztrim(src, (3, -13), 'audio_file.wav')
  • clip (VideoNode) – Input clip needed to determine framerate for audio timecodes and clip.num_frames for negative indexing.

  • trims (Union[List[Tuple[Optional[int], Optional[int]]], Tuple[Optional[int], Optional[int]]]) –

    Either a list of 2-tuples, or one tuple of 2 ints.

    Empty slicing must represented with a None.

    src[:10]+src[-5:] must be entered as trims=[(None, 10), (-5, None)].

    Single frame slices must be represented as a normal slice.

    src[15] must be entered as trims=(15, 16).

  • audio_file (str) – A string to the source audio file’s location (i.e. ‘/path/to/audio_file.ext’). If the extension is not recognized as a valid audio file extension for FFmpeg’s encoders, the audio will be re-encoded to WAV losslessly.

  • outfile (Optional[str]) – Either a filename ‘out.ext’ or a full path ‘/path/to/out.ext’ that will be used for the trimmed audio file. The extension will be automatically inserted for you, and if it is given, it will be overwritten by the input audio_file’s extension. If left blank, defaults to audio_file_cut.ext.

  • ffmpeg_path (Optional[str]) – Set this if ffmpeg is not in your PATH. If ffmpeg exists in your PATH, it will automatically be detected and used.

  • quiet (bool) – Suppresses most console output from FFmpeg.

  • timecodes_file (Optional[str]) – Timecodes v2 file (generated by vspipe, ffms2, etc.) for variable-frame-rate clips. Not needed for CFR clips.


Returns output file name as a string for other functions.

acsuite.concat(audio_files, outfile, *, ffmpeg_path=None, quiet=False, debug=False)[source]

Function to concatenate mutliple audio files.

All audio files must have the same extension, and the outfile must have the same extension as the audio files.

  • audio_files (List[str]) – List of strings representing audio file paths (i.e. ['file1.wav', 'file2.wav']).

  • outfile (str) – String representing desired filename for the concatenated audio.

  • ffmpeg_path (Optional[str]) – Set this if ffmpeg is not in your PATH. If ffmpeg exists in your PATH, it will automatically be detected and used.

  • quiet (bool) – Suppresses most console output from FFmpeg.

acsuite.f2ts(f, *, precision=3, timecodes_file=None, src_clip)[source]

Converts frame number to a timestamp based on framerate.

Can handle variable-frame-rate clips as well, using similar methods to that of vspipe --timecodes. For VFR clips, will use a timecodes v2 file if given, else will fallback to the slower src_clip.frames() method. Meant to be called as a functools.partial with src_clip specified before-hand.

  • f (int) – Frame number (indexed from 0). Can be negative, indexing from the last frame of the src_clip.

  • precision (int) – An integer in [0, 3, 6, 9] representing the precision of the timestamp (second, millisecond, microsecond, nanosecond respectively).

  • timecodes_file (Optional[str]) – An optional path to a v2 timecodes plaintext file for VFR clips (not used for CFR clips). If not given, will fallback to a much slower method of determining each frame’s timestamp.

  • src_clip (VideoNode) – A VapourSynth clip for determining the timestamp. src_clip.fps is used for CFR clips, and the frame props (_DurationNum and _DurationDen) are used for VFR clips if a timecodes_file is not given.


A string representing the timestamp of the requested frame number.

from functools import partial
import vapoursynth as vs
core = vs.core

clip = core.std.BlankClip()
ts = partial(f2ts, src_clip=clip)

ts(5), ts(9), ts(clip.num_frames), ts(-1)
# ('00:00:00.208', '00:00:00.375', '00:00:10.000', '00:00:09.958')

Cached function to return a list of timecodes for vfr clips.

The first call to this function can be very expensive depending on the src_clip length and the source filter used.

Subsequent calls on the same clip will return the previously generated list of timecodes. The timecodes are floats representing seconds from the start of the src_clip.

If you have rich installed, will output a pretty progress bar as this process can take a long time.