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).
Under the hood, stempeg uses ffmpeg for reading and writing multistream audio, optionally MP4Box 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 (>= 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:
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
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
, 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
.
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 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):
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
:
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
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.FilesWriter
Stems will be saved into multiple files. For the naming,basename(path)
is ignored and just the parent ofpath
and itsextension
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 ofMP4Box
.
⚠️ Warning: Muxing stems using ffmpeg leads to multi-stream files not compatible with Native Instrument Hardware or Software. Please use MP4Box if you use thestempeg.NISTemsWriter()
For more information on writing stems, see stempeg.write_stems
. An example that documents the advanced features of the writer, see 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.
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.
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.