drumscript 0.1.6__tar.gz → 0.2.1__tar.gz

{drumscript-0.1.6 → drumscript-0.2.1}/MANIFEST.in

@@ -14,14 +14,8 @@ prune docs
 prune local_tests
 prune tests
 prune test_audio
-prune machine-learning
-prune labeled_datasets
 prune .archive
 prune .development
 prune logs
 prune outputs
-prune terraform
-prune visuals
-prune .testing
-prune branch_note
-exclude Makefile
+prune visuals

{drumscript-0.1.6/DrumScript.egg-info → drumscript-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drumscript
-Version: 0.1.6
+Version: 0.2.1
 Summary: A Python package to convert drum audio to sheet music.
 Author-email: drumscript-admin <hello.drumscript@gmail.com>
 License-Expression: Apache-2.0
@@ -30,7 +30,7 @@ Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Classifier: Topic :: Scientific/Engineering :: Physics
-Requires-Python: <3.14,>=3.9
+Requires-Python: <3.13,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: demucs
@@ -57,28 +57,48 @@ Requires-Dist: shibuya>=2025.10.21; extra == "dev"
 Requires-Dist: ipywidgets>=8.1.8; extra == "dev"
 Requires-Dist: requests>=2.32.5; extra == "dev"
 Requires-Dist: ruff>=0.15.11; extra == "dev"
+Requires-Dist: twine>=6.2.0; extra == "dev"
+Requires-Dist: nbstripout>=0.8.2; extra == "dev"
 Dynamic: license-file
 
 # **`DrumScript`**
 
 <!--date_created: sun-15-june-2025-->
-<!--date_edited: thurs-18-june-2026--->
+<!--date_edited: thurd-20-august-2026--->
 
-**Workflow Status**
-
-[![Run Tests](https://github.com/DrumScript/DrumScript/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/DrumScript/DrumScript/actions/workflows/tests.yml)
+**DrumScript** is an open-source Python library and CLI tool for drum audio analysis and transcription. Give it a recording — a full mix or an isolated drum stem — and it will generate PDF sheet music, MIDI files, and MusicXML output. The `DrumScript` model is a **deterministic classifier**, and doesn't use AI/machine learning. Built for drummers and by drummers, it is - and always will be - an open-source community tool.
 
-**Demo Notebooks**
+> **Python >=3.9**
 
-[![Try DrumScript in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DrumScript/DrumScript/blob/main/docs/guide/interactive/drumscript_interactive_notebook.ipynb)
+**Workflow Status**
+> 
+[![Run Tests](https://github.com/DrumScript/DrumScript/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/DrumScript/DrumScript/actions/workflows/tests.yml)
+>
+**[Documentation](https://drumscript.github.io/DrumScript/)**
+>
+> **[Try DrumScript In Colab](https://colab.research.google.com/drive/15yBGu6WURPyiH-sEQ82g_2T2wKqiIPsq)**
+>
+> <a href="https://colab.research.google.com/drive/15yBGu6WURPyiH-sEQ82g_2T2wKqiIPsq" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>
 
-**DrumScript** is an open-source Python library and CLI tool for drum audio analysis and transcription. Give it a recording — a full mix or an isolated drum stem — and it will generate PDF sheet music, MIDI files, and MusicXML output. The `DrumScript` model is a **deterministic classifier**, and doesn't use AI/machine learning. Built for drummers and by drummers, it is - and always will be - an open-source community tool.
 
-> **Python >=3.9**
+- **[Features](#features)**
+- **[Project Structure](#project-structure)**
+- **[Installation](#installation)**
+- **[Quick Start](#quick-start)**
+- **[CLI Usage](#cli-usage)**
+- **[Contributing](#contributing)**
+- **[Testing](#testing)**
+- **[Benchmarking](#benchmarking)**
+- **[Traffic](#traffic)**
+- **[FAQs](#faqs)**
+- **[Changelog](CHANGELOG.md)**
+- **[Acknowledgements](#acknowledgements)**
+- **[Similar projects](#similar-projects)**
+- **[License](#license)**
 
-> **[Documentation](https://drumscript.github.io/DrumScript/)**
+---
 
-**Public Alpha (v0.1.4+) — June to August 2026**
+#### **Public Alpha (v0.1.4+) — ongoing since June 2026**
 
  - We're looking for early adopters and feedback
  - [Feedback on the classification model](https://github.com/DrumScript/DrumScript/issues), and help shape v1.0.0.
@@ -87,7 +107,7 @@ Dynamic: license-file
 
 > See the **[Roadmap](https://drumscript.github.io/DrumScript/guide/roadmap.html)** for what's planned.
 
-**What it looks like**
+#### **What it looks like**
 
 <!-- TODO: Replace with a GIF showing terminal output-->
 <!-- For now, this shows the PDF transcription output -->
@@ -96,46 +116,29 @@ Dynamic: license-file
 
 **Example 1: Simple groove**
 
-![DrumScript transcription output](./docs/_static/test_wav.png)
+<!---![DrumScript transcription output](./docs/_static/test_wav.png)-->
+![DrumScript transcription output](https://raw.githubusercontent.com/DrumScript/DrumScript/main//docs/_static/test_wav.png)
 
 **Example 2: A well-known Sabbath song**
 
-![DrumScript transcription output](./docs/_static/iron_man_1.png)
-![DrumScript transcription output](./docs/_static/iron_man_2.png)
-![DrumScript transcription output](./docs/_static/iron_man_3.png)
+<!---![DrumScript transcription output](./docs/_static/iron_man_1.png)--->
+<!---![DrumScript transcription output](./docs/_static/iron_man_2.png)--->
+<!---![DrumScript transcription output](./docs/_static/iron_man_3.png)--->
+![DrumScript transcription output](https://raw.githubusercontent.com/DrumScript/DrumScript/main/docs/_static/iron_man_1.png)
+![DrumScript transcription output](https://raw.githubusercontent.com/DrumScript/DrumScript/main/docs/_static/iron_man_2.png)
+![DrumScript transcription output](https://raw.githubusercontent.com/DrumScript/DrumScript/main/docs/_static/iron_man_3.png)
 
 ---
 
-- **[Features](#features)**
-- **[Installation](#installation)**
-- **[Quick Start](#quick-start)**
-- **[CLI Usage](#cli-usage)**
-- **[Contributing](#contributing)**
-- **[FAQs](#faqs)**
-- **[Similar projects](#similar-projects)**
-
----
-
-## Features
-
-- **Automatic Drum Transcription:** Detects kicks, snares, hi-hats, toms, and cymbals using a deterministic, rule-based classification engine — no machine learning required.
-- **Tempo Detection:** Automatically estimates BPM using a voting-system algorithm tuned for percussive audio.
-- **Onset Detection:** Onset detection method tuned to the physics of percussion audio rather than polyphonic instruments (piano, guitar, etc.).
-- **Stem Separation:** Uses the state-of-the-art [Demucs](https://github.com/adefossez/demucs) source separation model to isolate drums, bass, vocals, and other instruments from a full mix.
-- **Backing Track Generator:** Automatically remove the drums from any `.mp3` or `.wav` to create a drumless play-along track. Bass-only and vocal-only extraction also supported.
-- **Multiple Output Formats:** Export transcriptions to PDF sheet music, MIDI (`.mid`), and MusicXML (`.xml`) for import into DAWs and notation software (Logic Pro, Cubase, Ableton, MuseScore, Sibelius, etc.).
-- **Deterministic Classification:** DrumScript's core classification engine uses physics-based rules derived from acoustic analysis of real drum samples, not probabilistic AI/ML models.
-
-> **Note:** Some dependencies used by DrumScript (e.g. [Demucs](https://github.com/adefossez/demucs), [librosa](https://librosa.org/)) may internally use probabilistic methods. DrumScript's own classification engine is fully deterministic.
-
----
 
 ## Project Structure
+*[back](#drumscript)*
 
 See [`repository_structure.md`](repository_structure.md) for the full project layout.
 
 ```
 DrumScript/
+├── benchmarks/                 # mir_eval scripts for benchmarking DrumScript 
 ├── drumscript/                 # Main source package
 │   ├── __init__.py             # Public API (transcribe, load_audio, etc.)
 │   ├── main.py                 # CLI entry point
@@ -146,14 +149,33 @@ DrumScript/
 │   └── utils/                  # Helpers (ffmpeg installer, research scripts)
 ├── benchmarks/                 # Evaluation runners (see benchmarks/README.md)
 ├── docs/                       # Sphinx documentation
-├── tests/                      # pytest test suite (131 unit + 8 integration)
+├── tests/                      # pytest test suite (138 unit + 23 integration)
 ├── .github/workflows/          # CI/CD (tests, build, publish, docs)
 ├── pyproject.toml              # Package metadata and dependencies
 └── uv.lock                     # Pinned dependency versions
 ```
 
+---
+
+## Features
+*[back](#drumscript)*
+
+- **Automatic Drum Transcription:** Detects kicks, snares, hi-hats, toms, and cymbals using a deterministic, rule-based classification engine — no machine learning required.
+- **Tempo Detection:** Automatically estimates BPM using a voting-system algorithm tuned for percussive audio.
+- **Onset Detection:** Onset detection method tuned to the physics of percussion audio rather than polyphonic instruments (piano, guitar, etc.).
+- **Stem Separation:** Uses the state-of-the-art [Demucs](https://github.com/adefossez/demucs) source separation model to isolate drums, bass, vocals, and other instruments from a full mix.
+- **Backing Track Generator:** Automatically remove the drums from any `.mp3` or `.wav` to create a drumless play-along track. Bass-only and vocal-only extraction also supported.
+- **Multiple Output Formats:** Export transcriptions to PDF sheet music, MIDI (`.mid`), and MusicXML (`.xml`) for import into DAWs and notation software (Logic Pro, Cubase, Ableton, MuseScore, Sibelius, etc.).
+- **Deterministic Classification:** DrumScript's core classification engine uses physics-based rules derived from acoustic analysis of real drum samples, not probabilistic AI/ML models.
+
+> **Note:** Some dependencies used by DrumScript (e.g. [Demucs](https://github.com/adefossez/demucs), [librosa](https://librosa.org/)) may internally use probabilistic methods. DrumScript's own classification engine is fully deterministic.
+
+---
+
+
 
 ## Installation
+*[back](#drumscript)*
 
 **For users:**
 
@@ -195,6 +217,7 @@ DrumScript manages all dependencies via [`pyproject.toml`](pyproject.toml) using
 ---
 
 ## Quick Start
+*[back](#drumscript)*
 
 > Please note: DrumScript assumes you are providing **drum audio-only inputs by default** 
 
@@ -205,27 +228,35 @@ DrumScript manages all dependencies via [`pyproject.toml`](pyproject.toml) using
 ```python
 import drumscript as ds
 
-# Transcribe an isolated drum stem → PDF
-pdf_path = ds.transcribe("drum_audio.wav")
+# Transcribe an isolated drum stem → PDF + JSON + MIDI
+result = ds.transcribe("drum_audio.wav")
+print(result["pdf_path"])   # PDF sheet music
+print(result["json_path"])  # raw transcription data (JSON)
+print(result["midi_path"])  # MIDI file for DAW import
 
 # Transcribe a full song (separates drums automatically)
-pdf_path = ds.transcribe("full_song.mp3") # drum only audio
-pdf_path = ds.transcribe("full_song.mp3", full_song=True) # full song, tells DrumScript to extract the drums first and then transcribe
+result = ds.transcribe("full_song.mp3") # drum only audio
+result = ds.transcribe("full_song.mp3", full_song=True) # full song, tells DrumScript to extract the drums first and then transcribe
 
-# Get all intermediate results
+# Get all intermediate results (tempo, onsets, events, etc.)
 result = ds.transcribe("drum_audio.wav", verbose=True)
 print(f"Tempo: {result['tempo']:.1f} BPM")
 print(f"Events: {len(result['events'])}")
+print(f"PDF: {result['pdf_path']}")
+print(f"MIDI: {result['midi_path']}")
 ```
 
+> **Note (v0.2.0):** `transcribe()` now returns a dict with `pdf_path`, `json_path`, and `midi_path` keys. Using the return value as a plain string (e.g. `pdf = ds.transcribe(...)`) still works but is deprecated and will be removed in v1.0.0. Use `result["pdf_path"]` instead.
+
 ### Load and explore audio
 
 ```python
 import drumscript as ds
 
 # Load at native sample rate (for notebooks / exploration)
-audio_file = ds.load_audio("drum_audio.wav")
-print(f"Sample rate: {sr} Hz, Duration: {len(audio)/sr:.1f}s")
+audio, sr = ds.load_audio("drum_audio.wav")
+# print(f"Sample rate: {sr} Hz, Duration: {len(audio)/sr:.1f}s")
+print(f"Sample rate: {audio_file[1]} Hz, Duration: {len(audio_file[0])/audio_file[1]:.1f}s")
 
 # Detect tempo
 bpm = ds.detect_tempo("drum_audio.wav")
@@ -237,45 +268,32 @@ print(f"Tempo: {bpm:.1f} BPM")
 ```python
 import drumscript as ds
 
-# Extract just the drum stem
-drum_path = ds.extract_stems("full_song.mp3")
+# Extract just the drum stem from full polyphonic audio (let's call it "full_song.wav")
+# Not to be confused with "full_song" flag used in transcribe(), which is for when you want to extract stems before transcribing
+stem_split = ds.extract_stems("full_song.wav")
 
-# Create a drumless backing track in MP3
-results = ds.extract_stems(
-    "full_song.mp3",
-    drumless=True,
-    output_format="mp3",
-    verbose=True,
-)
-print(f"Backing track: {results['mix']}")
 ```
 
----
-
-## Benchmarking
-
-DrumScript includes a benchmarking framework for evaluating the classifier against standard ADT datasets using [`mir_eval`](https://github.com/mir-evaluation/mir_eval). Currently supports IDMT-SMT-Drums V2.
+### Create drumless backing track to your favourite songs
 
-```zsh
-# Install dev dependencies (includes mir_eval)
-uv sync --extra dev
+```python
+import drumscript as ds
 
-# Run the IDMT benchmark
-uv run --extra dev python benchmarks/run.py idmt \
-  --root /path/to/IDMT-SMT-DRUMS-V2
+# Remember to use mp3 flag if using mp3 audio
+# default input format is .wav
 
-# Run on a single subset with a limit
-uv run --extra dev python benchmarks/run.py idmt \
-  --root /path/to/IDMT-SMT-DRUMS-V2 \
-  --subset RealDrum --limit 5
+remove_drums = ds.extract_stems("full_song.wav",
+    drumless=True,
+    verbose=True,
+)
+print(f"Files written to: {remove_drums['output_directory']}")
+# The backing track is saved as <input>_no_drums.wav in that directory.
 ```
 
-Results are archived to `outputs/benchmarks/idmt/` with per-file metrics, summary statistics, and git commit tracking for reproducibility. See [`benchmarks/README.md`](benchmarks/README.md) for dataset setup and full usage.
-
-
 ---
 
 ## CLI Usage
+*[back](#drumscript)*
 
 DrumScript also provides a command-line interface.
 
@@ -324,11 +342,13 @@ drumscript full_song.mp3 --all-stems --format mp3
 # Classify rudiments
 drumscript snare_hit.wav --rudiment
 ```
+
 ---
 
 ## Contributing
+*[back](#drumscript)*
 
-We welcome contributions! DrumScript is intended to be a community-owned project.
+We welcome contributions! DrumScript is intended to be a community-owned project. You can also refer to detailed contributor guidance **[here](./docs/development/contributor_guidance.md)**
 
 - **[Open an Issue](https://github.com/DrumScript/DrumScript/issues/new)** for bugs or feature requests.
 - **[Submit a Pull Request](https://github.com/DrumScript/DrumScript/pulls)** for code changes.
@@ -339,7 +359,7 @@ We welcome contributions! DrumScript is intended to be a community-owned project
 **[hello.drumscript@gmail.com](mailto:hello.drumscript@gmail.com)**
 
 ## Alpha Priorities (v0.0.4 < v1.0.0) 
-The alpha phase runs between 01 June and 31 August 2026
+The alpha phase began June 2026. We expect it to run through late 2026 and into 2027 — beta is targeted on API stability and benchmark validation rather than a fixed calendar date.
 
 **What works today:**
 
@@ -357,10 +377,65 @@ The alpha phase runs between 01 June and 31 August 2026
 - Stabilising the public API ahead of the beta freeze
 - Community feedback collection
 
+---
+
+### Publishing a new release
+*[back](#drumscript)*
+
+We use an automated pipeline to publish new versions to PyPI. All releases must use a specific tag format: `vX.Y.Z` (for example, `v0.2.0`).
+
+**To publish a release via GitHub Actions (Recommended):**
+1. Go to the **Actions** tab in this repository.
+2. Click on **Create Release** on the left menu.
+3. Click **Run workflow** on the right.
+4. Type in your new version number (e.g., `0.2.0`) and click **Run workflow**. GitHub will handle the rest!
+
+---
+
+## Testing
+*[back](#drumscript)*
+
+For detailed instructions on testing and publishing via the command line, please see our **[Testing Guidance](tests/README.md).**
+
+---
+
+## Benchmarking
+*[back](#drumscript)*
+
+DrumScript includes a benchmarking framework for evaluating the classifier against standard ADT datasets using [`mir_eval`](https://github.com/mir-evaluation/mir_eval). Currently supports IDMT-SMT-Drums V2.
+
+```zsh
+# Install dev dependencies (includes mir_eval)
+uv sync --extra dev
+
+# Run the IDMT benchmark
+uv run --extra dev python benchmarks/run.py idmt \
+  --root /path/to/IDMT-SMT-DRUMS-V2
+
+# Run on a single subset with a limit
+uv run --extra dev python benchmarks/run.py idmt \
+  --root /path/to/IDMT-SMT-DRUMS-V2 \
+  --subset RealDrum --limit 5
+```
+
+Results are archived to `outputs/benchmarks/idmt/` with per-file metrics, summary statistics, and git commit tracking for reproducibility. See [`benchmarks/README.md`](benchmarks/README.md) for dataset setup and full usage.
+
+---
+
+## Traffic
+*[back](#drumscript)*
+
+We collate usage over time for performance-monitoring. Live repository statistics — updated daily:
+
+- [**View Report (PDF)**](https://github.com/DrumScript/DrumScript/blob/github-repo-stats/DrumScript/DrumScript/latest-report/report.pdf)
+<!--- [**View Report (HTML)**](https://github.com/DrumScript/DrumScript/blob/github-repo-stats/DrumScript/DrumScript/latest-report/report.html)
+
+> Views, clones, stars, forks, top referrers and popular paths. Data collected automatically via [github-repo-stats](https://github.com/jgehrcke/github-repo-stats). Defaults to last 14 days in outputs. Raw data available on **[github-repo-stats](https://github.com/DrumScript/DrumScript/tree/github-repo-stats/DrumScript/DrumScript/ghrs-data**) branch-->
 
 ---
 
 ## FAQs
+*[back](#drumscript)*
 
 ### Why doesn't DrumScript include `ffmpeg` as a dependency?
 
@@ -381,20 +456,19 @@ DrumScript's own classification engine is **fully deterministic** — it uses ph
 ---
 
 ## Acknowledgements
+*[back](#drumscript)*
 
 1. **[Demucs](https://github.com/adefossez/demucs)** — The stem splitting functionality is built upon the work of [@adefossez](https://github.com/adefossez).
 2. **[librosa](https://librosa.org/)** — For foundational audio processing tools.
 3. **[@nanaoto](https://github.com/nanaoto)** — For building the `mir_eval` benchmarking infrastructure and IDMT-SMT-Drums V2 adapter (PR [#273](https://github.com/DrumScript/DrumScript/pull/273)).
 
----
-
-## License
 
-[Apache License 2.0](LICENSE)
 
 ---
 ## Similar Projects
 
+*[back](#drumscript)*
+
 DrumScript has no affiliation with any of the projects below. They are listed for context and reference.
 
 * **[librosa](https://librosa.org/)** — The spectral analysis library that powers DrumScript's onset detection and feature extraction.
@@ -406,4 +480,18 @@ DrumScript has no affiliation with any of the projects below. They are listed fo
 
 ---
 
+## License
+*[back](#drumscript)*
+
+**[Apache License 2.0](LICENSE)**
+
+**Copyright 2026 DrumScript**
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+---
+
+
 <!--END-->