How it works#

Description: This document serves dual purpose:

  1. It outlines the purpose of specific modules in DrumScript, object-wise.

  2. It outlines key definitions to clarify the methodology used.

DrumScript: How it works#

audio_processor/#

Module overview

This module handles all raw audio manipulation. It is currently the most active part of the package, handling:

  • Stem Splitting (stem_splitter.py): Uses the Demucs source separation model (by adefossez) to isolate drum frequencies from a full audio mix.

  • Tempo Detection (tempo_detector.py): Uses a deterministic “Voting System” to analyse the tempogram and determine the most likely BPM across the entire track.

  • Onset Detection (onset_detector.py): Finds where the drum hits actually occur (i.e., onset_events).

  • Feature Extraction (feature_extractor.py): Extracts numerical features (spectral centroid, bandwidth, zero-crossing rate) from these events for use in the classifier.

drum_classifier/#

Module overview

This module is the core logic engine of the package (currently in active R&D). It no longer involves training a model. Instead, it:

  • Takes the numerical features for each drum hit from the audio_processor/ module.

  • Applies a pre-defined set of rules and thresholds (a deterministic classification system) to determine which drum was played.

  • Outputs a structured list of all the classified drum events.

classify.py#

This script is the Rule Engine. It contains the core logic for the classification. Its main job is to take the acoustic features of a drum hit and make a decision. Specifically, classify.py:

  • Loads the features extracted for every onset in an audio file.

  • Runs these features through a series of conditional checks (e.g., “if the spectral centroid is below X and the energy is high, classify as a kick drum”).

  • Generates the final list of classified events (e.g., prediction_output.json), detailing what drum was hit and when.

generate_score.py#

This is a Utility and Testing Script. It’s designed to quickly visualise the output of the classifier without running the entire application pipeline. Specifically, generate_score.py:

  • Reads the list of classified events produced by classify.py.

  • Uses the notation_generator/ module to convert that list directly into a sheet music file (.pdf)

  • Allows for rapid testing and debugging of the classification rules by providing immediate visual feedback on the transcription quality.