Read and write stem multistream audio files
stempeg = stems + ffmpeg
python package to read and write STEM files. Technically, STEMs are MP4 files with multiple audio streams and additional metatdata. stempeg is a python interface for ffmpeg particularly made to read and write multi stream MP4 audio files.
1. Installation of ffmpeg Library
stempeg relies on ffmpeg (tested: 4.1, 4.0.2, 3.4 and 2.8.6) to decode the stems file format. For encoding 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
Decoding is supported with any recent build of ffmpeg. 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.
You can install ffmpeg with
libfdk-aac support manually as following:
- Mac: use homebrew:
brew install ffmpeg --with-fdk-aac
- Ubuntu Linux: See installation script here.
- Using Docker (Mac, Windows, Linux):
docker pull jrottenberg/ffmpeg
2. Installation of the stempeg package
Installation via PyPI using pip
pip install stempeg
There are very few freely available stem files. We included a small test track from the Canadian rock-band The Easton Ellises. The band released them under Creative Commons license CC BY-NC-SA 3.0.
To use the included stem example you can use
import stempeg S, rate = stempeg.read_stems(stempeg.example_stem_path())
S is the stem tensor that includes the time domain signals scaled to
[-1..1]. The shape is
(stems, samples, channels).
Reading individual stem ids
you can read individual substreams of the stem file 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)
to read an excerpt from the stem instead of the full file, you can provide 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
read_stems is called repeatedly, it always does two system calls, one for getting the file info and one for the actual reading. To speed this up you could provide the
Info object to
read_stems if the number of streams, the number of channels and the samplerate is identical.
file_path = stempeg.example_stem_path() info = stempeg.Info(file_path) S, _ = stempeg.read_stems(file_path, info=info)
Writing stem files from a numpy tensor
stempeg.write_stems(S, "output.stem.mp4", rate=44100)
:warning: Warning: Muxing stems using ffmpeg might lead to non-conform stem files. Please use MP4Box, if you need a reliable result.
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
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size stempeg-0.1.8-py3-none-any.whl (509.8 kB)||File type Wheel||Python version py3||Upload date||Hashes View|
|Filename, size stempeg-0.1.8.tar.gz (511.5 kB)||File type Source||Python version None||Upload date||Hashes View|