Pre-release

This release is a pre-release and may not be stable for production use.

BestSource

build codespell

BestSource (abbreviated as BS) is a cross-platform wrapper library around FFmpeg that ensures always sample and frame accurate access to audio and video with good seeking performance for everything except some lossy audio formats.

It can be used as either a C++ library directly or through the combined VapourSynth and Avisynth+ plugin that's included.

Dependencies

  • FFmpeg 8.1.x and FFmpeg 8.0.x supported. Later releases may or may not work but FFmpeg API breakages are quite common and don't always generate compilation errors. Only libavcodec, libavformat, libavutil libraries are required.
  • xxHash

Windows Compilation

On Windows the easiest way to compile the the dependencies is to use vcpkg to install ffmpeg[avcodec,avdevice,avfilter,avformat,swresample,swscale,zlib,bzip2,core,dav1d,gpl,version3,lzma,nvcodec,qsv,vulkan,openssl,xml2]:x64-windows-static and xxhash:x64-windows-static. Do however note that this is without Little CMS2 support. Use the latest version of Visual Studio. It should automatically find all the required libraries if you used vcpkg.

Linux and MacOS Compilation

Requires pkg-config, meson and ninja-build.

git clone https://github.com/vapoursynth/bestsource.git --depth 1
cd bestsource
meson setup build
meson compile -C build
meson install -C build

Known issues and limitations

  • Seeking performance in mpeg/ts/vob files can be quite poor due to the FFmpeg demuxer
  • Seeking and decoding performance for lossy audio formats (aac, mp3, dts, ac3, vorbis) can be poor
  • VC1 codec is unseekable due to FFmpeg not having bitexact output after seeking
  • The unholy combination of VFR H264 in AVI has poor seeking performance
  • Needs FFmpeg compiled with Little CMS2 or the color information reported for most image files will be less complete
  • Mod files can't be decoded correctly using libmodplug due to the library not having repeatable bitexact output
  • Gray+alpha format isn't supported in Avisynth+ and as a result only the Y component is returned
  • Files with dimensions that aren't a multiple of the subsampling value will be cropped

VapourSynth usage

bs.AudioSource(string source[, int track = -1, int adjustdelay = -1, int threads = 0, bint enable_drefs = False, bint use_absolute_path = False, float drc_scale = 0, int cachemode = 1, string cachepath, int cachesize = 100, bint showprogress = True, maxdecoders = 0])

bs.VideoSource(string source[, int track = -1, int variableformat = -1, int fpsnum = -1, int fpsden = 1, bint rff = False, int threads = 0, int seekpreroll = 20, bint enable_drefs = False, bint use_absolute_path = False, int cachemode = 1, string cachepath , int cachesize = 100, string hwdevice, int extrahwframes = 9, string timecodes, int start_number, int viewid = 0, bint showprogress = True, maxdecoders = 0, bool hwfallback = True, exporttimestamps = False])

bs.TrackInfo(string source[, bint enable_drefs = False, bint use_absolute_path = False])

bs.Metadata(string source[, int track, bint enable_drefs = False, bint use_absolute_path = False])

bs.SetDebugOutput(bint enable = False)

bs.SetFFmpegLogLevel(int level = <quiet log level>)

The TrackInfo function only returns the most basic information about a track which is the type, codec and disposition. Its main use is to be able to implement custom track selection logic for the source functions.

The Metadata function returns all the file or track metadata as key-value pairs depending on whether or not track is specified.

Avisynth+ usage

BSAudioSource(string source[, int track = -1, int adjustdelay = -1, int threads = 0, bool enable_drefs = False, bool use_absolute_path = False, float drc_scale = 0, int cachemode = 1, string cachepath, int cachesize = 100, int maxdecoders = 0])

BSVideoSource(string source[, int track = -1, int fpsnum = -1, int fpsden = 1, bool rff = False, int threads = 0, int seekpreroll = 20, bool enable_drefs = False, bool use_absolute_path = False, int cachemode = 1, string cachepath, int cachesize = 100, string hwdevice, int extrahwframes = 9, string timecodes, int start_number, int variableformat = 0, int viewid = 0, int maxdecoders = 0, bool hwfallback = True])

BSSource(string source[, int atrack = -1, int vtrack = -1, int fpsnum = -1, int fpsden = 1, bool rff = False, int threads = 0, int seekpreroll = 20, bool enable_drefs = False, bool use_absolute_path = False, int cachemode = 1, string cachepath, int acachesize = 100, int vcachesize = 100, string hwdevice, int extrahwframes = 9, string timecodes, int start_number, int variableformat = 0, int adjustdelay = -1, float drc_scale = 0, int viewid = 0, int maxdecoders = 0, bool hwfallback = True])

BSSetDebugOutput(bool enable = False)

BSSetFFmpegLogLevel(int level = <quiet log level>)

Note that the BSSource function by default will silently ignore errors when opening audio and in that case only return the video track. However if atrack is explicitly set failure to open the audio track will return an error.

Argument explanation

source: The source filename. Note that image sequences also can be opened by using %d or %03d for zero padded numbers. Sequences may start at any number between 0 and 4 unless otherwise specified with start_number. It's also possible to pass urls and other ffmpeg protocols like concat.

track: Either a positive number starting from 0 specifying the absolute track number or a negative number to select the nth audio or video track. Throws an error on wrong type or no matching track.

adjustdelay: Adjust audio start time relative to a video track number. Pass -2 to disable and -1 to be relative to the first video track if one exists. Specifying a non-video track is equivalent to passing -2. Note that the offset is always relative to the first CPU-decodable frame in the stream meaning that it may not be the correct delay when hwmode and variableformat are used.

variableformat: Allow format changes in the output for video. To only allow fixed format output pass 0 or greater to choose the nth encountered format as the output format. Any frames not matching the chosen format are dropped. If the file is constant format (most are) this setting does nothing.

fpsnum: Convert the source material to constant framerate. Cannot be combined with rff.

fpsden: Convert the source material to constant framerate. Used in conjunction with fpsnum.

rff: Apply RFF flags to the video. If the video doesn't have or use RFF flags the output is unchanged compare to when the option is disabled. Cannot be combined with fpsnum.

threads: Number of threads to use for decoding. Pass 0 to autodetect.

seekpreroll: Number of frames before the requested frame to cache when seeking.

enable_drefs: Option passed to the FFmpeg mov demuxer.

use_absolute_path: Option passed to the FFmpeg mov demuxer.

drc_scale: Apply dynamic range compression to ac3 audio. 0 = None and 1.0 = Normal.

cachemode:

0 = Never read or write index to disk
1 = Always try to read index but only write index to disk when it will make a noticeable difference on subsequent runs and store index files in a subtree of *cachepath*
2 = Always try to read and write index to disk and store index files in a subtree of *cachepath*
3 = Always try to read index but only write index to disk when it will make a noticeable difference on subsequent runs and store index files with *cachepath* used as the base filename with track number and index extension automatically appended 
4 = Always try to read and write index to disk and store index files with *cachepath* used as the base filename with track number and index extension automatically appended

cachepath: The path where cache files are written. Note that the actual index files are written into subdirectories using based on the source location. Defaults to %LOCALAPPDATA% on Windows and $XDG_CACHE_HOME/bsindex if set otherwise ~/bsindex on other operation systems in mode 1 and 2. For mode 3 and 4 it defaults to source.

cachesize: Maximum internal cache size in MB.

hwdevice: The interface to use for hardware decoding. Depends on OS and hardware. On windows d3d11va, cuda and vulkan (H264, HEVC and AV1) are probably the ones most likely to work. Defaults to CPU decoding. Will throw errors for formats where hardware decoding isn't possible.

extrahwframes: The number of additional frames to allocate when hwdevice is set. The number required is unknowable and found through trial and error. The default may be too high or too low. FFmpeg unfortunately is this badly designed.

timecodes: Writes a timecode v2 file with all frame times to the file if specified. Note that this option will produce an error if any frame has an unknown timestamp which would result in an invalid timecode file.

start_number: The first number of image sequences.

viewid: The view id to output, this is currently only used for some mv-hevc files and is quite rare.

showprogress: Print indexing progress as VapourSynth information level log messages.

maxdecoders: The maximum number of decoder instances kept around, defaults to 4 but when decoding high resolution content it may be beneficial to reduce it to 1 to reduce peak memory usage. For example 4k h264 material will use approximately 250MB of ram in addition to the specified cache size for decoder instance. Passing a number outside the 1-4 range will set it to the biggest number supported.

hwfallback: Automatically fall back to CPU decoding if hardware decoding can't be used for the current video track when hwdevice is set. Note that the fallback only happens when a hardware decoder is unavailable and not on any other category of error such as hwdevice having an invalid value.

exporttimestamps: Returns an additional array of all frame timestamps and its timebase in timebasenum and timebaseden containing all frame times addition to the video clip. Note that unknown timestamps can be set to AV_NOPTS_VALUE. Cannot be combined with rff and fpsnum modes.

level: The log level of the FFmpeg library. By default quiet. See FFmpeg documentation for allowed constants. Mostly useful for debugging purposes.

Project links

Data verified by PyPI on Jul 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (21.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for myrsloik from gravatar.com myrsloik

Credits

Author: Fredrik Mellbin

GitHub Statistics

Data verified by PyPI on Jul 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Tags

source video audio

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vapoursynth_bestsource-20.0rc1.tar.gz (67.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

vapoursynth_bestsource-20.0rc1-py3-none-win_amd64.whl (12.3 MB view details)

Uploaded Python 3Windows x86-64

vapoursynth_bestsource-20.0rc1-py3-none-musllinux_1_2_x86_64.whl (14.5 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

vapoursynth_bestsource-20.0rc1-py3-none-musllinux_1_2_aarch64.whl (13.1 MB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

vapoursynth_bestsource-20.0rc1-py3-none-manylinux_2_28_x86_64.whl (13.5 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

vapoursynth_bestsource-20.0rc1-py3-none-manylinux_2_28_aarch64.whl (12.2 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ ARM64

vapoursynth_bestsource-20.0rc1-py3-none-macosx_15_0_x86_64.whl (10.6 MB view details)

Uploaded Python 3macOS 15.0+ x86-64

vapoursynth_bestsource-20.0rc1-py3-none-macosx_15_0_arm64.whl (8.9 MB view details)

Uploaded Python 3macOS 15.0+ ARM64

File details

Details for the file vapoursynth_bestsource-20.0rc1.tar.gz.

File metadata

  • Download URL: vapoursynth_bestsource-20.0rc1.tar.gz
  • Upload date:
  • Size: 67.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for vapoursynth_bestsource-20.0rc1.tar.gz
Algorithm Hash digest
SHA256 bee4d4ff93a680804d8346f9aefe6ed1b9b73e4d16f66b0c450524c7758d41c2
MD5 9393fac31c4a63a05e99508e414f9df0
BLAKE2b-256 1383ac59a4170daa2706d2377760087b1d7c6d4472521af2913fe20e5a73f731

See more details on using hashes here.

Provenance

The following attestation bundles were made for vapoursynth_bestsource-20.0rc1.tar.gz:

Publisher: build.yml on vapoursynth/bestsource

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vapoursynth_bestsource-20.0rc1-py3-none-win_amd64.whl.

File metadata

File hashes

Hashes for vapoursynth_bestsource-20.0rc1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 49c98dc38c8aad2dd5a7e2c81cf3b334f4875e83d12938b14873189a44894f54
MD5 6049d4acfbfc2933a89fa650cd9b8fa8
BLAKE2b-256 7710e24a84976985b4771fc7728cc02cd9460268d0483d9496dd0d854c4d7557

See more details on using hashes here.

Provenance

The following attestation bundles were made for vapoursynth_bestsource-20.0rc1-py3-none-win_amd64.whl:

Publisher: build.yml on vapoursynth/bestsource

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vapoursynth_bestsource-20.0rc1-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for vapoursynth_bestsource-20.0rc1-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 8b11b0af377af28553fa09c285b748c6414fae73dd17c51a4ba5839ebc25e16d
MD5 0c921e82215bacad282db65684a34750
BLAKE2b-256 738836b530ece77979727d93dffed8682af2b11dfe5af795c359662565927b84

See more details on using hashes here.

Provenance

The following attestation bundles were made for vapoursynth_bestsource-20.0rc1-py3-none-musllinux_1_2_x86_64.whl:

Publisher: build.yml on vapoursynth/bestsource

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vapoursynth_bestsource-20.0rc1-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for vapoursynth_bestsource-20.0rc1-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 500599d994b8326a6a0f1540eaf54c65a8281289b02449b21fd92e7b5be1ff56
MD5 aae55cff68a7bd42393baf18710d97f3
BLAKE2b-256 240830efdcdaf920d158ce53657e3c611e2451ac7f7d127938c25329059a527b

See more details on using hashes here.

Provenance

The following attestation bundles were made for vapoursynth_bestsource-20.0rc1-py3-none-musllinux_1_2_aarch64.whl:

Publisher: build.yml on vapoursynth/bestsource

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vapoursynth_bestsource-20.0rc1-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for vapoursynth_bestsource-20.0rc1-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 c8cc322fb91c2f785faffe138aebf0eb5ce530e1863009e730ed790ab0c9cdea
MD5 dc0b913a7733c90ac26a2fca8b0f70bc
BLAKE2b-256 ac5d9db0da367799054f1f982a13f7cbc33ed1eae3384cd66770999ac1b38513

See more details on using hashes here.

Provenance

The following attestation bundles were made for vapoursynth_bestsource-20.0rc1-py3-none-manylinux_2_28_x86_64.whl:

Publisher: build.yml on vapoursynth/bestsource

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vapoursynth_bestsource-20.0rc1-py3-none-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for vapoursynth_bestsource-20.0rc1-py3-none-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 ca92651f3393f07f1765dc0d11e169771a48600c27665ccfb341c9b2853a53d2
MD5 0dec165bfa14a10a006e40a19b193494
BLAKE2b-256 16c67fd5399a98ef67c6899fcbdfa50437a2ea5c4469b13d5a43034287f1f4d1

See more details on using hashes here.

Provenance

The following attestation bundles were made for vapoursynth_bestsource-20.0rc1-py3-none-manylinux_2_28_aarch64.whl:

Publisher: build.yml on vapoursynth/bestsource

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vapoursynth_bestsource-20.0rc1-py3-none-macosx_15_0_x86_64.whl.

File metadata

File hashes

Hashes for vapoursynth_bestsource-20.0rc1-py3-none-macosx_15_0_x86_64.whl
Algorithm Hash digest
SHA256 0c0e206d63cdcd45f176505be3ca16d26a8005eabcb49f1278454416bb7c3aff
MD5 45ae0e8fbe84cf83d6c45eb2cc878c4d
BLAKE2b-256 cb00fb1cd221e7076cfd5c19b6239a2bb58c23eeba2f453b433d143366e5458d

See more details on using hashes here.

Provenance

The following attestation bundles were made for vapoursynth_bestsource-20.0rc1-py3-none-macosx_15_0_x86_64.whl:

Publisher: build.yml on vapoursynth/bestsource

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vapoursynth_bestsource-20.0rc1-py3-none-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for vapoursynth_bestsource-20.0rc1-py3-none-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 05a727c7331fff7ed94413b95b1fc972eb91b9cbffbe960a13294d77da2a0d1e
MD5 f043530baf474cced714904154b68358
BLAKE2b-256 666a745ed6d460e3beeb0d75bb2a63dad46a7da21e748a03868f79fe35c94454

See more details on using hashes here.

Provenance

The following attestation bundles were made for vapoursynth_bestsource-20.0rc1-py3-none-macosx_15_0_arm64.whl:

Publisher: build.yml on vapoursynth/bestsource

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

Pre-release

22rc1

8 files

21.0

8 files

20.0

8 files

Pre-release

20.0rc2

8 files

This release
Pre-release

20.0rc1 This release

8 files

19.0

8 files

18.0

10 files

17.0

6 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page