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.
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 fdk-aac
. If 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
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 stempeg.example_stem_path()
.
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)
.
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])
to read an excerpt from the stem instead of the full file, you can provide 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
if 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: Muxing stems using ffmpeg might lead to non-conform stem files. Please use MP4Box, if you need a reliable result.
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