musci 0.1.0__tar.gz

musci-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sami Akhnoukh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

musci-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+prune downloads
+prune .venv
+prune {{pkgetc}}
+global-exclude .env
+global-exclude .env.*
+global-exclude *.mp3
+global-exclude *.py[cod]

musci-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: musci
+Version: 0.1.0
+Summary: Bulk Spotify, Apple Music & YouTube playlist 320kbps MP3 downloader and DJ BPM/Camelot key analyzer
+Author: Sami Akhnoukh
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sakhnoukh/musci
+Project-URL: Repository, https://github.com/sakhnoukh/musci
+Keywords: dj,music,mp3,bpm,camelot,spotify,apple-music,playlist
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yt-dlp<2027.0.0,>=2025.1.1
+Requires-Dist: yt-dlp-ejs<1.0.0,>=0.3.0
+Requires-Dist: librosa<0.12.0,>=0.10.2
+Requires-Dist: numpy<3.0.0,>=1.26.0
+Requires-Dist: soundfile<0.14.0,>=0.12.1
+Requires-Dist: mutagen<1.49.0,>=1.47.0
+Requires-Dist: httpx<0.29.0,>=0.27.0
+Requires-Dist: typer<0.22.0,>=0.12.0
+Requires-Dist: rich<15.0.0,>=13.7.0
+Requires-Dist: python-dotenv<2.0.0,>=1.0.1
+Provides-Extra: dev
+Requires-Dist: pytest<10.0.0,>=8.0.0; extra == "dev"
+Requires-Dist: build<2.0.0,>=1.2.0; extra == "dev"
+Requires-Dist: twine<7.0.0,>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# musci
+
+I wanted to start fucking around with mixing music, and couldn't be asked to download mp3s myself from youtube, so i thought i'd do something about it. 
+Could extend this to be like an npm package, but i still don't know if Spotify and Apple apis will let me do that. 
+
+Bulk playlist MP3 downloader and DJ mixing prep CLI. Supports **Spotify playlists/albums/tracks**, **Apple Music playlists/albums/songs**, **YouTube playlists/videos**, SoundCloud/Bandcamp links, and text tracklists.
+
+Downloads audio concurrently as **320kbps CBR MP3s** (constant bitrate to prevent beatgrid drift in Rekordbox, Serato, Traktor, and CDJs) with **BPM + Camelot Wheel key detection** and **ID3v2.3** tagging.
+
+## Install (No Code / `.venv` Needed)
+
+Install `ffmpeg` + `pipx` once on macOS (Homebrew), then install `musci` globally:
+
+```bash
+brew install ffmpeg pipx
+pipx ensurepath
+pipx install git+https://github.com/sakhnoukh/musci.git
+```
+*(Once published to PyPI, this becomes `pipx install musci`.)*
+
+## Launch the Interactive Terminal UI
+
+Just run:
+
+```bash
+musci
+```
+
+`musci` boots with an animated **3D neon logo + spinning DJ turntable/EQ sprite**, system readiness indicators, a command cheat sheet, and an interactive `musci ▸` prompt where you can simply **paste any playlist URL** and hit Enter (or run commands directly from your shell below).
+
+### Direct CLI Commands
+
+#### 1. Download a Spotify, Apple Music, or YouTube playlist (with BPM & Camelot key detection)
+
+```bash
+musci download "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"
+musci download "https://music.apple.com/us/playlist/..."
+musci download "https://www.youtube.com/playlist?list=PL..."
+```
+
+### 2. Fast download-only mode (skip BPM & key analysis)
+
+```bash
+musci download "https://open.spotify.com/playlist/..." --download-only
+```
+
+### 3. Prefix filenames with `[BPM - Camelot]` for quick folder browsing
+
+```bash
+musci download "https://open.spotify.com/playlist/..." --prefix-filename
+# Produces e.g.: [128 - 8A] Artist - Track Title.mp3
+```
+
+### 4. Batch download from a text file of playlist URLs or `Artist - Title` lines
+
+```bash
+musci download --from-file playlists.txt --workers 6 -o ./downloads
+```
+
+### 5. Analyze an existing folder of MP3s for BPM & Camelot key
+
+```bash
+musci analyze ./downloads/my-playlist --prefix-filename
+```
+
+## Large Spotify Playlists (>100 tracks)
+
+Out of the box, `musci` reads public Spotify playlists with **zero configuration** (up to ~100 tracks per playlist via Spotify's public embed metadata).
+
+For playlists with **100+ tracks** (using your Spotify Premium account):
+
+1. Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) and click **Create app**:
+   - **Redirect URI**: `http://127.0.0.1:8888/callback`
+   - Check **Web API** and click **Save**.
+2. Run the guided setup wizard (prompts for your Client ID & Secret, stores them securely in `~/.config/musci/.env`, and opens browser login automatically):
+   ```bash
+   musci spotify-setup
+   ```
+4. **If the 100+ track playlist was created by someone else**: Under Spotify's 2026 Developer Mode rules, the API only returns full 100+ item lists for playlists you own or collaborate on. In Spotify Desktop, open the playlist, click `...` -> **Add to other playlist** -> **New playlist** (takes 2 seconds), and pass your new playlist's link to `musci download`.
+
+## Notes for DJ Mixing
+
+- **320kbps CBR MP3**: All downloads are encoded using `libmp3lame` at 320kbps constant bitrate with ID3v2.3 tags (`TBPM`, `TKEY`, `TIT2`, `TPE1`, `TALB`, cover art) for reliable beatgrids across Rekordbox, Serato, VirtualDJ, Traktor, and Mixxx.
+- **Source Audio Quality**: YouTube native audio streams top out around 128–160kbps Opus/AAC. While 320kbps CBR MP3 packaging works well for bedroom mixing, set prep, and casual gigs, large club sound systems benefit from lossless/DJ-pool masters.
+- **Incremental Sync**: Each output folder stores `.musci-manifest.json` so re-running `musci download` on an updated playlist skips tracks you already downloaded.

musci-0.1.0/README.md

@@ -0,0 +1,85 @@
+# musci
+
+I wanted to start fucking around with mixing music, and couldn't be asked to download mp3s myself from youtube, so i thought i'd do something about it. 
+Could extend this to be like an npm package, but i still don't know if Spotify and Apple apis will let me do that. 
+
+Bulk playlist MP3 downloader and DJ mixing prep CLI. Supports **Spotify playlists/albums/tracks**, **Apple Music playlists/albums/songs**, **YouTube playlists/videos**, SoundCloud/Bandcamp links, and text tracklists.
+
+Downloads audio concurrently as **320kbps CBR MP3s** (constant bitrate to prevent beatgrid drift in Rekordbox, Serato, Traktor, and CDJs) with **BPM + Camelot Wheel key detection** and **ID3v2.3** tagging.
+
+## Install (No Code / `.venv` Needed)
+
+Install `ffmpeg` + `pipx` once on macOS (Homebrew), then install `musci` globally:
+
+```bash
+brew install ffmpeg pipx
+pipx ensurepath
+pipx install git+https://github.com/sakhnoukh/musci.git
+```
+*(Once published to PyPI, this becomes `pipx install musci`.)*
+
+## Launch the Interactive Terminal UI
+
+Just run:
+
+```bash
+musci
+```
+
+`musci` boots with an animated **3D neon logo + spinning DJ turntable/EQ sprite**, system readiness indicators, a command cheat sheet, and an interactive `musci ▸` prompt where you can simply **paste any playlist URL** and hit Enter (or run commands directly from your shell below).
+
+### Direct CLI Commands
+
+#### 1. Download a Spotify, Apple Music, or YouTube playlist (with BPM & Camelot key detection)
+
+```bash
+musci download "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"
+musci download "https://music.apple.com/us/playlist/..."
+musci download "https://www.youtube.com/playlist?list=PL..."
+```
+
+### 2. Fast download-only mode (skip BPM & key analysis)
+
+```bash
+musci download "https://open.spotify.com/playlist/..." --download-only
+```
+
+### 3. Prefix filenames with `[BPM - Camelot]` for quick folder browsing
+
+```bash
+musci download "https://open.spotify.com/playlist/..." --prefix-filename
+# Produces e.g.: [128 - 8A] Artist - Track Title.mp3
+```
+
+### 4. Batch download from a text file of playlist URLs or `Artist - Title` lines
+
+```bash
+musci download --from-file playlists.txt --workers 6 -o ./downloads
+```
+
+### 5. Analyze an existing folder of MP3s for BPM & Camelot key
+
+```bash
+musci analyze ./downloads/my-playlist --prefix-filename
+```
+
+## Large Spotify Playlists (>100 tracks)
+
+Out of the box, `musci` reads public Spotify playlists with **zero configuration** (up to ~100 tracks per playlist via Spotify's public embed metadata).
+
+For playlists with **100+ tracks** (using your Spotify Premium account):
+
+1. Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) and click **Create app**:
+   - **Redirect URI**: `http://127.0.0.1:8888/callback`
+   - Check **Web API** and click **Save**.
+2. Run the guided setup wizard (prompts for your Client ID & Secret, stores them securely in `~/.config/musci/.env`, and opens browser login automatically):
+   ```bash
+   musci spotify-setup
+   ```
+4. **If the 100+ track playlist was created by someone else**: Under Spotify's 2026 Developer Mode rules, the API only returns full 100+ item lists for playlists you own or collaborate on. In Spotify Desktop, open the playlist, click `...` -> **Add to other playlist** -> **New playlist** (takes 2 seconds), and pass your new playlist's link to `musci download`.
+
+## Notes for DJ Mixing
+
+- **320kbps CBR MP3**: All downloads are encoded using `libmp3lame` at 320kbps constant bitrate with ID3v2.3 tags (`TBPM`, `TKEY`, `TIT2`, `TPE1`, `TALB`, cover art) for reliable beatgrids across Rekordbox, Serato, VirtualDJ, Traktor, and Mixxx.
+- **Source Audio Quality**: YouTube native audio streams top out around 128–160kbps Opus/AAC. While 320kbps CBR MP3 packaging works well for bedroom mixing, set prep, and casual gigs, large club sound systems benefit from lossless/DJ-pool masters.
+- **Incremental Sync**: Each output folder stores `.musci-manifest.json` so re-running `musci download` on an updated playlist skips tracks you already downloaded.

musci-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68.0,<85.0", "wheel>=0.40,<1.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "musci"
+version = "0.1.0"
+description = "Bulk Spotify, Apple Music & YouTube playlist 320kbps MP3 downloader and DJ BPM/Camelot key analyzer"
+readme = "README.md"
+license = "MIT"
+authors = [{name = "Sami Akhnoukh"}]
+requires-python = ">=3.11,<3.15"
+keywords = ["dj", "music", "mp3", "bpm", "camelot", "spotify", "apple-music", "playlist"]
+classifiers = [
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Analysis",
+]
+dependencies = [
+    "yt-dlp>=2025.1.1,<2027.0.0",
+    "yt-dlp-ejs>=0.3.0,<1.0.0",
+    "librosa>=0.10.2,<0.12.0",
+    "numpy>=1.26.0,<3.0.0",
+    "soundfile>=0.12.1,<0.14.0",
+    "mutagen>=1.47.0,<1.49.0",
+    "httpx>=0.27.0,<0.29.0",
+    "typer>=0.12.0,<0.22.0",
+    "rich>=13.7.0,<15.0.0",
+    "python-dotenv>=1.0.1,<2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0,<10.0.0",
+    "build>=1.2.0,<2.0.0",
+    "twine>=5.0.0,<7.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/sakhnoukh/musci"
+Repository = "https://github.com/sakhnoukh/musci"
+
+[project.scripts]
+musci = "musci.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

musci-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

musci-0.1.0/src/musci/__init__.py

@@ -0,0 +1,3 @@
+"""musci: Bulk playlist MP3 downloader and DJ BPM/key analyzer."""
+
+__version__ = "0.1.0"

musci-0.1.0/src/musci/analyzer.py

@@ -0,0 +1,196 @@
+"""Audio BPM and Camelot Wheel key detection using librosa."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import shutil
+import subprocess
+
+import librosa
+from mutagen import File as MutagenFile
+import numpy as np
+import soundfile as sf
+
+from musci.models import CAMELOT_MAP, AnalysisResult
+
+SAMPLE_RATE = 22050
+MAX_ANALYSIS_WINDOW_SEC = 90.0
+
+# Krumhansl-Kessler pitch-class key profiles (C, C#, D, ..., B)
+KRUMHANSL_MAJOR = np.array(
+    [6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88],
+    dtype=np.float64,
+)
+KRUMHANSL_MINOR = np.array(
+    [6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17],
+    dtype=np.float64,
+)
+
+
+def fold_bpm_into_range(bpm: float, min_bpm: float = 70.0, max_bpm: float = 180.0) -> float:
+    """Fold half-time or double-time tempo estimates into [min_bpm, max_bpm]."""
+    if bpm <= 0 or min_bpm <= 0 or max_bpm <= min_bpm:
+        return max(0.0, bpm)
+    adjusted = float(bpm)
+    while adjusted < min_bpm:
+        adjusted *= 2.0
+    while adjusted > max_bpm:
+        adjusted /= 2.0
+    return round(adjusted, 2)
+
+
+def detect_bpm_from_samples(
+    y: np.ndarray,
+    sr: int = SAMPLE_RATE,
+    min_bpm: float = 70.0,
+    max_bpm: float = 180.0,
+) -> float:
+    """Estimate BPM from a mono waveform with sub-BPM beat-interval refinement."""
+    hop_length = 256
+    onset_env = librosa.onset.onset_strength(y=y, sr=sr, hop_length=hop_length)
+    start_bpm = max(min_bpm, min(max_bpm, 124.0))
+    tempo, beat_frames = librosa.beat.beat_track(
+        onset_envelope=onset_env,
+        sr=sr,
+        hop_length=hop_length,
+        start_bpm=start_bpm,
+    )
+    raw_bpm = float(np.asarray(tempo).flat[0])
+
+    # Refine integer-frame lag quantization using tracked inter-beat intervals
+    if len(beat_frames) >= 5:
+        beat_times = librosa.frames_to_time(beat_frames, sr=sr, hop_length=hop_length)
+        ibis = np.diff(beat_times)
+        median_ibi = float(np.median(ibis))
+        if median_ibi > 0:
+            inliers = ibis[np.abs(ibis - median_ibi) <= 0.12 * median_ibi]
+            if len(inliers) >= 3:
+                raw_bpm = 60.0 / float(np.mean(inliers))
+
+    if raw_bpm <= 0.0:
+        fallback = librosa.feature.rhythm.tempo(
+            onset_envelope=onset_env,
+            sr=sr,
+            hop_length=hop_length,
+            start_bpm=start_bpm,
+        )
+        raw_bpm = float(np.asarray(fallback).flat[0])
+    return fold_bpm_into_range(raw_bpm, min_bpm=min_bpm, max_bpm=max_bpm)
+
+
+def _pearson_corr(a: np.ndarray, b: np.ndarray) -> float:
+    a_centered = a - np.mean(a)
+    b_centered = b - np.mean(b)
+    denom = float(np.linalg.norm(a_centered) * np.linalg.norm(b_centered))
+    if denom < 1e-12:
+        return 0.0
+    return float(np.dot(a_centered, b_centered) / denom)
+
+
+def detect_key_from_samples(y: np.ndarray, sr: int = SAMPLE_RATE) -> tuple[str, str, float]:
+    """Detect (camelot_key, musical_key, confidence) using spectrogram-domain HPSS chromagram."""
+    stft_mag = np.abs(librosa.stft(y=y, n_fft=4096, hop_length=2048))
+    harm_mag, _ = librosa.decompose.hpss(stft_mag, kernel_size=15, margin=2.0)
+    chroma = librosa.feature.chroma_stft(S=harm_mag**2, sr=sr, n_fft=4096)
+    chroma_vec = np.mean(chroma, axis=1)
+
+    if float(np.max(chroma_vec)) < 1e-8:
+        camelot, musical = CAMELOT_MAP[(9, "minor")]
+        return camelot, musical, 0.0
+
+    best_corr = -2.0
+    best_key_pair = (9, "minor")
+
+    for pitch_class in range(12):
+        maj_corr = _pearson_corr(chroma_vec, np.roll(KRUMHANSL_MAJOR, pitch_class))
+        if maj_corr > best_corr:
+            best_corr = maj_corr
+            best_key_pair = (pitch_class, "major")
+
+        min_corr = _pearson_corr(chroma_vec, np.roll(KRUMHANSL_MINOR, pitch_class))
+        if min_corr > best_corr:
+            best_corr = min_corr
+            best_key_pair = (pitch_class, "minor")
+
+    camelot_key, musical_key = CAMELOT_MAP[best_key_pair]
+    confidence = round(max(0.0, min(1.0, best_corr)), 3)
+    return camelot_key, musical_key, confidence
+
+
+def _probe_duration_sec(audio_path: Path) -> float:
+    meta = MutagenFile(str(audio_path))
+    if meta is not None and getattr(meta, "info", None) is not None and getattr(meta.info, "length", 0):
+        return float(meta.info.length)
+    try:
+        return float(sf.info(str(audio_path)).duration)
+    except Exception:
+        return float(librosa.get_duration(path=str(audio_path)))
+
+
+def _choose_analysis_window(audio_path: Path, max_window_sec: float = MAX_ANALYSIS_WINDOW_SEC) -> tuple[float, float | None]:
+    total_sec = _probe_duration_sec(audio_path)
+    if total_sec <= max_window_sec:
+        return 0.0, None
+    # Sample from the middle of the track to avoid beatless DJ intros/outros
+    offset = max(0.0, (total_sec - max_window_sec) / 2.0)
+    return round(offset, 2), max_window_sec
+
+
+def _load_audio_window(audio_path: Path, offset: float, duration: float | None) -> tuple[np.ndarray, int]:
+    ffmpeg_bin = shutil.which("ffmpeg")
+    if ffmpeg_bin:
+        cmd = [ffmpeg_bin, "-v", "error"]
+        if offset > 0:
+            cmd.extend(["-ss", str(offset)])
+        if duration is not None:
+            cmd.extend(["-t", str(duration)])
+        cmd.extend(
+            [
+                "-i",
+                str(audio_path),
+                "-vn",
+                "-ac",
+                "1",
+                "-ar",
+                str(SAMPLE_RATE),
+                "-f",
+                "f32le",
+                "pipe:1",
+            ]
+        )
+        proc = subprocess.run(cmd, capture_output=True, check=False)
+        if proc.returncode == 0 and proc.stdout:
+            samples = np.frombuffer(proc.stdout, dtype=np.float32).copy()
+            return samples, SAMPLE_RATE
+
+    y, sr = librosa.load(
+        str(audio_path),
+        sr=SAMPLE_RATE,
+        mono=True,
+        offset=offset,
+        duration=duration,
+    )
+    return y, int(sr)
+
+
+def analyze_audio_file(
+    audio_path: Path,
+    min_bpm: float = 70.0,
+    max_bpm: float = 180.0,
+    max_window_sec: float = MAX_ANALYSIS_WINDOW_SEC,
+) -> AnalysisResult:
+    """Load representative window of an audio file and compute BPM & Camelot/musical key."""
+    offset, duration = _choose_analysis_window(audio_path, max_window_sec=max_window_sec)
+    y, sr = _load_audio_window(audio_path, offset=offset, duration=duration)
+    if y.size < SAMPLE_RATE or float(np.max(np.abs(y))) < 1e-6:
+        raise ValueError(f"Audio file '{audio_path.name}' is too short or silent to analyze.")
+
+    bpm = detect_bpm_from_samples(y, sr=sr, min_bpm=min_bpm, max_bpm=max_bpm)
+    camelot_key, musical_key, confidence = detect_key_from_samples(y, sr=sr)
+    return AnalysisResult(
+        bpm=bpm,
+        bpm_rounded=int(round(bpm)),
+        camelot_key=camelot_key,
+        musical_key=musical_key,
+        key_confidence=confidence,
+    )