{"id":13800165,"url":"https://github.com/faroit/stempeg","last_synced_at":"2025-10-18T19:52:50.663Z","repository":{"id":45804221,"uuid":"91799059","full_name":"faroit/stempeg","owner":"faroit","description":"Python I/O for STEM audio files","archived":false,"fork":false,"pushed_at":"2024-08-29T08:31:28.000Z","size":1569,"stargazers_count":98,"open_issues_count":7,"forks_count":16,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-29T16:05:58.895Z","etag":null,"topics":["ffmpeg","multitrack","native-instruments","python","stems"],"latest_commit_sha":null,"homepage":"https://faroit.github.io/stempeg","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faroit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-19T11:25:46.000Z","updated_at":"2025-03-11T06:45:58.000Z","dependencies_parsed_at":"2024-06-18T20:08:55.866Z","dependency_job_id":"996e5705-0b50-4736-ae47-6125f5670b6b","html_url":"https://github.com/faroit/stempeg","commit_stats":{"total_commits":98,"total_committers":6,"mean_commits":"16.333333333333332","dds":0.5204081632653061,"last_synced_commit":"0c938ba1927952698c9768e8853ebd32a5f537af"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faroit%2Fstempeg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faroit%2Fstempeg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faroit%2Fstempeg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faroit%2Fstempeg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faroit","download_url":"https://codeload.github.com/faroit/stempeg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369952,"owners_count":20927928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ffmpeg","multitrack","native-instruments","python","stems"],"created_at":"2024-08-04T00:01:10.016Z","updated_at":"2025-10-18T19:52:50.584Z","avatar_url":"https://github.com/faroit.png","language":"Python","readme":"# stempeg = stems + ffmpeg\n\n\n[![Build Status](https://github.com/faroit/stempeg/workflows/CI/badge.svg)](https://github.com/faroit/stempeg/actions?query=workflow%3ACI+branch%3Amaster+event%3Apush)\n[![Latest Version](https://img.shields.io/pypi/v/stempeg.svg)](https://pypi.python.org/pypi/stempeg)\n[![Supported Python versions](https://img.shields.io/pypi/pyversions/stempeg.svg)](https://pypi.python.org/pypi/stempeg)\n\nPython package to read and write [STEM](https://www.native-instruments.com/en/specials/stems/) audio files.\nTechnically, stems are audio containers that combine multiple audio streams and metadata in a single audio file. This makes it ideal to playback multitrack audio, where users can select the audio sub-stream during playback (e.g. supported by VLC).\n\nUnder the hood, _stempeg_ uses [ffmpeg](https://www.ffmpeg.org/) for reading and writing multistream audio, optionally [MP4Box](https://github.com/gpac/gpac) is used to create STEM files that are compatible with Native Instruments hardware and software.\n\n#### Features\n\n- robust and fast interface for ffmpeg to read and write any supported format from/to numpy.\n- reading supports seeking and duration.\n- control container and codec as well as bitrate when compressed audio is written.\n- store multi-track audio within audio formats by aggregate streams into channels (concatenation of pairs of\nstereo channels).\n- support for internal ffmpeg resampling furing read and write.\n- create mp4 stems compatible to Native Instruments traktor.\n- using multiprocessing to speed up reading substreams and write multiple files.\n\n## Installation\n\n### 1. Installation of ffmpeg Library\n\n_stempeg_ relies on [ffmpeg](https://www.ffmpeg.org/) (\u003e= 3.2 is suggested).\n\nThe Installation if ffmpeg differ among operating systems. If you use [anaconda](https://anaconda.org/anaconda/python) you can install ffmpeg on Windows/Mac/Linux using the following command:\n\n```\nconda install -c conda-forge ffmpeg\n```\n\nNote that for better quality encoding it is recommended to install ffmpeg with `libfdk-aac` codec support as following:\n\n* _MacOS_: use homebrew: `brew install ffmpeg --with-fdk-aac`\n* _Ubuntu/Debian Linux_: See installation script [here](https://gist.github.com/rafaelbiriba/7f2d7c6f6c3d6ae2a5cb).\n* _Docker_: `docker pull jrottenberg/ffmpeg`\n\n### 1a. (optional) Installation of MP4Box\n\nIf you plan to write stem files with full compatibility with Native Instruments Traktor DJ hardware and software, you need to install [MP4Box](https://github.com/gpac/gpac).\n\n* _MacOS_: use homebrew: `brew install gpac`\n* _Ubuntu/Debian Linux_: `apt-get install gpac`\n\nFurther installation instructions for all operating systems can be found [here](https://gpac.wp.imt.fr/downloads/).\n\n### 2. Installation of the _stempeg_ package\n\nA) Installation via PyPI using pip\n\n```\npip install stempeg\n```\n\nB) Installation via conda\n\n```\nconda install -c conda-forge stempeg\n```\n\n## Usage\n\n![stempeg_scheme](https://user-images.githubusercontent.com/72940/102477776-16960a00-405d-11eb-9389-1ea9263cf99d.png)\n\n### Reading audio\n\nStempeg can read multi-stream and single stream audio files, thus, it can replace your normal audio loaders for 1d or 2d (mono/stereo) arrays.\n\nBy default [`read_stems`](https://faroit.com/stempeg/read.html#stempeg.read.read_stems), assumes that multiple substreams can exit (default `reader=stempeg.StreamsReader()`).\nTo support multi-stream, even when the audio container doesn't support multiple streams\n(e.g. WAV), streams can be mapped to multiple pairs of channels. In that\ncase, `reader=stempeg.ChannelsReader()`, can be passed. Also see:\n[`stempeg.ChannelsWriter`](https://faroit.com/stempeg/write.html#stempeg.write.ChannelsWriter).\n\n```python\nimport stempeg\nS, rate = stempeg.read_stems(stempeg.example_stem_path())\n```\n\n`S` is a numpy tensor that includes the time domain signals scaled to `[-1..1]`. The shape is `(stems, samples, channels)`. An detailed documentation of the `read_stems` can [be viewed here](https://faroit.com/stempeg/read.html#stempeg.read.read_stems). Note, a small stems excerpt from [The Easton Ellises](https://www.heise.de/ct/artikel/c-t-Remix-Wettbewerb-The-Easton-Ellises-2542427.html#englisch), licensed under Creative Commons CC BY-NC-SA 3.0 is included and can be accessed using `stempeg.example_stem_path()`.\n\n#### Reading individual streams\n\nIndividual substreams of the stem file can be read by passing the corresponding stem id (starting from 0):\n\n```python\nS, rate = stempeg.read_stems(stempeg.example_stem_path(), stem_id=[0, 1])\n```\n\n#### Read excerpts (set seek position)\n\nExcerpts from the stem instead of the full file can be read by providing start (`start`) and duration (`duration`) in seconds to `read_stems`:\n\n```python\nS, _ = stempeg.read_stems(stempeg.example_stem_path(), start=1, duration=1.5)\n# read from second 1.0 to second 2.5\n```\n\n### Writing audio\n\nAs seen in the flow chart above, stempeg supports multiple ways to write multi-track audio.\n\n#### Write multi-channel audio\n\n[`stempeg.write_audio`](http://faroit.com/stempeg/write.html#stempeg.write.write_audio) can be used for single-stream, multi-channel audio files.\nStempeg wraps a number of ffmpeg parameter to resample the output sample rate and adjust the audio codec, if necessary.\n\n```python\nstempeg.write_audio(path=\"out.mp4\", data=S, sample_rate=44100.0, output_sample_rate=48000.0, codec='aac', bitrate=256000)\n```\n\n#### Writing multi-stream audio\n\nWriting stem files from a numpy tensor can done with.\n\n```python\nstempeg.write_stems(path=\"output.stem.mp4\", data=S, sample_rate=44100, writer=stempeg.StreamsWriter())\n```\n\nAs seen in the flow chart above, stempeg supports multiple ways to write multi-stream audio.\nEach of the method has different number of parameters. To select a method one of the following setting and be passed:\n\n* `stempeg.FilesWriter`\n    Stems will be saved into multiple files. For the naming,\n    `basename(path)` is ignored and just the\n    parent of `path`  and its `extension` is used.\n* `stempeg.ChannelsWriter`\n    Stems will be saved as multiple channels.\n* `stempeg.StreamsWriter` **(default)**.\n    Stems will be saved into a single a multi-stream file.\n* `stempeg.NIStemsWriter`\n    Stem will be saved into a single multistream audio.\n    Additionally Native Instruments Stems compabible\n    Metadata is added. This requires the installation of\n    `MP4Box`.\n\n\u003e :warning: __Warning__: Muxing stems using _ffmpeg_ leads to multi-stream files not compatible with Native Instrument Hardware or Software. Please use [MP4Box](https://github.com/gpac/gpac) if you use the `stempeg.NISTemsWriter()`\n\nFor more information on writing stems, see  [`stempeg.write_stems`](https://faroit.com/stempeg/write.html#stempeg.write.write_stems).\nAn example that documents the advanced features of the writer, see [readwrite.py](/examples/readwrite.py).\n\n### Use the command line tools\n\n_stempeg_ provides a convenient cli tool to convert a stem to multiple wavfiles. The `-s` switch sets the start, the `-t` switch sets the duration.\n\n```bash\nstem2wav The Easton Ellises - Falcon 69.stem.mp4 -s 1.0 -t 2.5\n```\n\n## F.A.Q\n\n#### How can I improve the reading performance?\n\n`read_stems` is called repeatedly, it always does two system calls, one for getting the file info and one for the actual reading speed this up you could provide the `Info` object to `read_stems` if the number of streams, the number of channels and the sample rate is identical.\n\n```python\nfile_path = stempeg.example_stem_path()\ninfo = stempeg.Info(file_path)\nS, _ = stempeg.read_stems(file_path, info=info)\n```\n\n#### How can the quality of the encoded stems be increased\n\nFor __Encoding__ it is recommended to use the Fraunhofer AAC encoder (`libfdk_aac`) which is not included in the default ffmpeg builds. Note that the conda version currently does _not_ include `fdk-aac`. If `libfdk_aac` is not installed _stempeg_ will use the default `aac` codec which will result in slightly inferior audio quality.\n","funding_links":[],"categories":["Audio Related Packages"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaroit%2Fstempeg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaroit%2Fstempeg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaroit%2Fstempeg/lists"}