Read and write stem/multistream audio files
stempeg = stems + ffmpeg
Python package to read and write STEM 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).
- 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.
1. Installation of ffmpeg Library
stempeg relies on ffmpeg (>= 3.2 is suggested).
The Installation if ffmpeg differ among operating systems. If you use anaconda 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.
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.
- MacOS: use homebrew:
brew install gpac
- Ubuntu/Debian Linux:
apt-get install gpac
Further installation instructions for all operating systems can be found here.
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
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.
read_stems, assumes that multiple substreams can exit (default
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
reader=stempeg.ChannelsReader(), can be passed. Also see:
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. Note, a small stems excerpt from The Easton Ellises, licensed under Creative Commons CC BY-NC-SA 3.0 is included and can be accessed using
Reading individual streams
Individual substreams of the stem file can be read by passing the corresponding stem id (starting from 0):
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
S, _ = stempeg.read_stems(stempeg.example_stem_path(), start=1, duration=1.5) # read from second 1.0 to second 2.5
As seen in the flow chart above, stempeg supports multiple ways to write multi-track audio.
Write multi-channel audio
stempeg.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.
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.
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.FilesWriterStems will be saved into multiple files. For the naming,
basename(path)is ignored and just the parent of
stempeg.ChannelsWriterStems will be saved as multiple channels.
stempeg.StreamsWriter(default). Stems will be saved into a single a multi-stream file.
stempeg.NIStemsWriterStem will be saved into a single multistream audio. Additionally Native Instruments Stems compabible Metadata is added. This requires the installation of
:warning: Warning: Muxing stems using ffmpeg leads to multi-stream files not compatible with Native Instrument Hardware or Software. Please use MP4Box if you use the
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.
stem2wav The Easton Ellises - Falcon 69.stem.mp4 -s 1.0 -t 2.5
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.
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
libfdk_aac is not installed stempeg will use the default
aac codec which will result in slightly inferior audio quality.
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.