# stempeg = stems + ffmpeg
[](https://travis-ci.org/faroit/stempeg)
[](https://pypi.python.org/pypi/stempeg)
[](https://pypi.python.org/pypi/stempeg)
Python package to read and write [STEM](https://www.native-instruments.com/en/specials/stems/) audio files.
Technically, 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).
Under 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.
#### Features
- robust and fast interface for ffmpeg to read and write any supported format from/to numpy.
- reading supports seeking and duration.
- control container and codec as well as bitrate when compressed audio is written.
- store multi-track audio within audio formats by aggregate streams into channels (concatenation of pairs of
stereo channels).
- support for internal ffmpeg resampling furing read and write.
- create mp4 stems compatible to Native Instruments traktor.
- using multiprocessing to speed up reading substreams and write multiple files.
## Installation
### 1. Installation of ffmpeg Library
_stempeg_ relies on [ffmpeg](https://www.ffmpeg.org/) (>= 3.2 is suggested).
The 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:
```
conda install -c conda-forge ffmpeg
```
Note that for better quality encoding it is recommended to install ffmpeg with `libfdk-aac` codec support as following:
* _MacOS_: use homebrew: `brew install ffmpeg --with-fdk-aac`
* _Ubuntu/Debian Linux_: See installation script [here](https://gist.github.com/rafaelbiriba/7f2d7c6f6c3d6ae2a5cb).
* _Docker_: `docker pull jrottenberg/ffmpeg`
### 1a. (optional) Installation of MP4Box
If 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).
* _MacOS_: use homebrew: `brew install gpac`
* _Ubuntu/Debian Linux_: `apt-get install gpac`
Further installation instructions for all operating systems can be found [here](https://gpac.wp.imt.fr/downloads/).
### 2. Installation of the _stempeg_ package
A) Installation via PyPI using pip
```
pip install stempeg
```
B) Installation via conda
```
conda install -c conda-forge stempeg
```
## Usage
### Reading audio
Stempeg can read multi-stream and single stream audio files, thus, it can replace your normal audio loaders for 1d or 2d (mono/stereo) arrays.
By default [`read_stems`](https://faroit.com/stempeg/read.html#stempeg.read.read_stems), assumes that multiple substreams can exit (default `reader=stempeg.StreamsReader()`).
To support multi-stream, even when the audio container doesn't support multiple streams
(e.g. WAV), streams can be mapped to multiple pairs of channels. In that
case, `reader=stempeg.ChannelsReader()`, can be passed. Also see:
[`stempeg.ChannelsWriter`](https://faroit.com/stempeg/write.html#stempeg.write.ChannelsWriter).
```python
import stempeg
S, rate = stempeg.read_stems(stempeg.example_stem_path())
```
`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()`.
#### Reading individual streams
Individual substreams of the stem file can be read by passing the corresponding stem id (starting from 0):
```python
S, rate = stempeg.read_stems(stempeg.example_stem_path(), stem_id=[0, 1])
```
#### Read excerpts (set seek position)
Excerpts from the stem instead of the full file can be read by providing start (`start`) and duration (`duration`) in seconds to `read_stems`:
```python
S, _ = stempeg.read_stems(stempeg.example_stem_path(), start=1, duration=1.5)
# read from second 1.0 to second 2.5
```
### Writing audio
As seen in the flow chart above, stempeg supports multiple ways to write multi-track audio.
#### Write multi-channel audio
[`stempeg.write_audio`](http://faroit.com/stempeg/write.html#stempeg.write.write_audio) can be used for single-stream, multi-channel audio files.
Stempeg wraps a number of ffmpeg parameter to resample the output sample rate and adjust the audio codec, if necessary.
```python
stempeg.write_audio(path="out.mp4", data=S, sample_rate=44100.0, output_sample_rate=48000.0, codec='aac', bitrate=256000)
```
#### Writing multi-stream audio
Writing stem files from a numpy tensor can done with.
```python
stempeg.write_stems(path="output.stem.mp4", data=S, sample_rate=44100, writer=stempeg.StreamsWriter())
```
As seen in the flow chart above, stempeg supports multiple ways to write multi-stream audio.
Each of the method has different number of parameters. To select a method one of the following setting and be passed:
* `stempeg.FilesWriter`
Stems will be saved into multiple files. For the naming,
`basename(path)` is ignored and just the
parent of `path` and its `extension` is used.
* `stempeg.ChannelsWriter`
Stems will be saved as multiple channels.
* `stempeg.StreamsWriter` **(default)**.
Stems will be saved into a single a multi-stream file.
* `stempeg.NIStemsWriter`
Stem will be saved into a single multistream audio.
Additionally Native Instruments Stems compabible
Metadata is added. This requires the installation of
`MP4Box`.
> :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()`
For more information on writing stems, see [`stempeg.write_stems`](https://faroit.com/stempeg/write.html#stempeg.write.write_stems).
An example that documents the advanced features of the writer, see [readwrite.py](/examples/readwrite.py).
### Use the command line tools
_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.
```bash
stem2wav The Easton Ellises - Falcon 69.stem.mp4 -s 1.0 -t 2.5
```
## F.A.Q
#### How can I improve the reading performance?
`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.
```python
file_path = stempeg.example_stem_path()
info = stempeg.Info(file_path)
S, _ = stempeg.read_stems(file_path, info=info)
```
#### How can the quality of the encoded stems be increased
For __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.
Raw data
{
"_id": null,
"home_page": "http://github.com/faroit/stempeg",
"name": "stempeg",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "stems audio reader",
"author": "Fabian-Robert Stoeter",
"author_email": "mail@faroit.com",
"download_url": "https://files.pythonhosted.org/packages/b9/cf/cb133ea8d24a29ef8b0873e8cd8dbfbc023988e11402dc1c34c2d29136a6/stempeg-0.2.3.tar.gz",
"platform": "",
"description": "# stempeg = stems + ffmpeg\n\n\n[](https://travis-ci.org/faroit/stempeg)\n[](https://pypi.python.org/pypi/stempeg)\n[](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/) (>= 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\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> :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\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Read and write stem/multistream audio files",
"version": "0.2.3",
"project_urls": {
"Bug Reports": "https://github.com/faroit/stempeg/issues",
"Homepage": "http://github.com/faroit/stempeg"
},
"split_keywords": [
"stems",
"audio",
"reader"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8de584adc8506b61ca9f205d9dcc5558b6b5b1fa477c45616f553a0ca1b8020d",
"md5": "e53970edb45bf1f0e884e37e88864f54",
"sha256": "130f384aafeb4429718421c7437bb1c9e24c851ae55f8b1de4d26c0d59ddb6a4"
},
"downloads": -1,
"filename": "stempeg-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e53970edb45bf1f0e884e37e88864f54",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 963513,
"upload_time": "2021-01-30T14:54:56",
"upload_time_iso_8601": "2021-01-30T14:54:56.015851Z",
"url": "https://files.pythonhosted.org/packages/8d/e5/84adc8506b61ca9f205d9dcc5558b6b5b1fa477c45616f553a0ca1b8020d/stempeg-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b9cfcb133ea8d24a29ef8b0873e8cd8dbfbc023988e11402dc1c34c2d29136a6",
"md5": "3518c83512abd485c4419d088f4ba81f",
"sha256": "840bb824504d713336da6a89d62790f7ba172a099dc96f8a2bb5d32148d1a96a"
},
"downloads": -1,
"filename": "stempeg-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "3518c83512abd485c4419d088f4ba81f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 965371,
"upload_time": "2021-01-30T14:54:59",
"upload_time_iso_8601": "2021-01-30T14:54:59.629288Z",
"url": "https://files.pythonhosted.org/packages/b9/cf/cb133ea8d24a29ef8b0873e8cd8dbfbc023988e11402dc1c34c2d29136a6/stempeg-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-01-30 14:54:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "faroit",
"github_project": "stempeg",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "stempeg"
}
JSON
