DrumScript Documentation

Open In Colab

DrumScript is an open-source Python library and CLI tool designed for drummers and audio engineers. DrumScript’s classification engine is deterministic. While its core mission is Automatic Drum Transcription (ADT) (converting drum recordings into sheet music), it also functions as a powerful Audio Toolbox for extracting drums from polyphonic tracks, creating backing tracks, and analysing rhythm.

#

Feature

What it does

1

Transcription

DrumScript converts drum audio → PDF sheet music . The --full-song flag also means you can give it a full song and it will extract the drums and transcribe

2

Stem Separation

Extracts drums from .wav and .mp3^ songs. Also supports extraction of bass, vocals, and other instruments

3

Backing Tracks

Give DrumScript a song and it will mute the drums to create a backing track for you

4

Tempo Detection

DrumScript estimates BPM from drum audio file based on tempogram-anaysis

^ .mp3 requires .ffmpeg (brew install ffmpeg)

Unlike most ADT systems, DrumScript’s classification engine is deterministic. DrumScript combines physics-derived spectral analysis: fundamental frequency, spectral centroid, energy ratios, and decay characteristics, applied through a rule-based pipeline built on librosa and Demucs. It also functions as a general-purpose audio toolbox: stem separation, drumless/bassless backing track generation, and tempo detection.

The project was born from one working drummer’s desire to make playing drums more fun and in an accessible way - it’s taken almost a year to build. v0.1.6 is part of the the Alpha release. Between 01 June and 31 August 2026 we are reaching out to communities, both musicians and academics alike, to find people to test - and hopefully improve - the deterministic classification model. For more info on where this is headed see roadmap or https://github.com/orgs/DrumScript/discussions

What can DrumScript do?

1. Audio-to-Sheet Music (Transcription)

Give DrumScript a recording of a drum beat, and it will generate a PDF Score.

  • Smart Detection: Uses signal processing to detect Kicks, Snares, and Hi-Hats.

  • Tempo Aware: Automatically calculates BPM.

  • Customizable: Supports custom time signatures (e.g., 3/4, 6/8).

2. Stem Splitting (The “De-Mixer”)

Powered by Demucs (Hybrid Transformer Source Separation), DrumScript can un-mix a full song.

  • Isolate Drums: Extract just the drum track from a full mix to study the groove.

  • Isolate Bass: Extract just the bass line to practice locking in.

  • Separate Everything: Explode a song into 4 stems: Drums, Bass, Vocals, Other.

3. Backing Track Generator

Want to play along to your favorite song but the drums are in the way?

  • Drumless Tracks: Automatically remove the drums from any .mp3 or .wav to create a play-along track.

  • Bassless Tracks: Mute the bass to practice your low-end theory.

4. Automatic Tempo Detection

Need to know the speed of a groove or drum loop? DrumScript can accurately estimate the global tempo of any percussive track.

  • Tempogram-First Approach: Calculates the Beats Per Minute (BPM) by generating a tempogram from the onset strength envelope

  • Automatic Tempo Detection: DrumScript automatically detects/calculates tempo when you provide a drum-only audio input. However, you can enforce a global tempo using the –tempo flag in transcribe() and the score generation will be built based on this.

DrumScript is an open-source Python library that converts drum audio (in .mp3, or .wav) to .pdf sheet music. It contains functions for you to automatically measure tempo of drum-only audio using Tempogram-first principles. DrumScript is unique to any other library because we do not use machine learning or AI. Our classification approach is a deterministic one.

DrumScript also extracts drum audio from any .mp3 or .wav audio file for you. Give it your favourite track, and it will do the job of extracting just the drum audio and then transcribe into handy .pdf sheet music. There stem-splitter functionality also extracts, optionally, the non-drum-parts of an audio track and provides it as a backing track for all you aspiring drummers and percussionists to play along to.

We are currently working on academic papers related to the deterministic method(s) used and will publish here in future There is also the plan to integrate the backing track extraction, drum only extraction, tempo detection and classification functions to a free-to-use UI that does not require login or store any of your uploads, nor their resultant outputs. More information will be provided soon! In the meantime, if you would like to be involved, get in touch! 🥁🚀

DrumScript was built for drummers, by drummers. It is - and always will be - a community-owned tool.

Example outputs

Example 1: Simple groove

DrumScript transcription output

Example 2: A well-known Sabbath song

DrumScript transcription output DrumScript transcription output DrumScript transcription output

About

Project Info

API Reference

API Reference

Development

Development

Getting Started

Getting Started

Release Notes

Versions

Runbooks

Runbooks

Theory

Theory

User Guide

User Guide