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.

Installation

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 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

2. Installation of the stempeg package

Installation via PyPI using pip

pip install stempeg

Usage

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().

Reading stems

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 read_stems:

S, _ = stempeg.read_stems(stempeg.example_stem_path(), start=1, duration=1.5)
# read from second 1.0 to second 2.5

Improve performance

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 stems

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