drumscript.transcribe#

transcribe(audio_path, *, full_song=False, time_signature='4/4', is_rudiment=False, output_dir='outputs', output_filename=None, verbose=False, full=None)[source]#

Run the full DrumScript transcription pipeline end-to-end.

Loads audio → optionally extracts the drum stem → detects tempo and onsets → classifies hits → builds the score → writes PDF, JSON, and MIDI output.

Parameters:

  • audio_path (str) – Path to the input audio file (full song or isolated drum stem).

  • full_song (bool, optional) – If True, run Demucs stem separation first to isolate the drum track. Set to False if your input is already an isolated drum stem.

  • time_signature (str, optional) – Time signature string in ‘N/D’ form (e.g. ‘4/4’, ‘6/8’).

  • is_rudiment (bool, optional) – If True, use the simpler classifier optimised for isolated single beats and rudiments rather than full polyphonic drum patterns.

  • output_dir (str, optional) – Directory to save output files. Created if it doesn’t exist. Defaults to ‘outputs/’.

  • output_filename (str, optional) – Output filename without extension. Defaults to ‘<input_stem>_transcription’.

  • verbose (bool, optional) – If True, return a dict with all intermediate results (tempo, onsets, events, paths) instead of just the output paths.

  • full (bool, optional) – Deprecated since v0.1.6, will be removed in v1.0.0. Use verbose instead. Passing full=True still works but emits a DeprecationWarning. Note: this is unrelated to full_song, which controls stem separation.

Returns:

A dict with pdf_path, json_path, and midi_path keys (backwards-compatible as a string via the PDF path until v1.0.0). If verbose=True, returns an extended dict with tempo, onsets, events, and other intermediate results.

Return type:

_TranscribeResult or dict

Examples:

Quick transcription of an isolated drum stem:

import drumscript as ds
result = ds.transcribe("drum_loop.wav")
print(result["pdf_path"])   # PDF sheet music
print(result["json_path"])  # raw transcription data
print(result["midi_path"])  # MIDI file for DAW import

Full song with stem separation, custom output, full results:

result = ds.transcribe(
    "full_song.mp3",
    full_song=True,
    time_signature="6/8",
    output_dir="./my_transcriptions",
    # full=True, # LEGACY CODE FROM V0.1.5 (--full flag replaced with deprecation shim, in place of --verbose)
    verbose=True
)
print(f"PDF: {result['pdf_path']}")
print(f"Detected tempo: {result['tempo']:.1f} BPM")
print(f"Onsets: {len(result['onsets'])}")