setlist-organiser 0.1.0__tar.gz

setlist_organiser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Hollingsworth
+
+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 OF OTHER DEALINGS IN THE
+SOFTWARE.

setlist_organiser-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: setlist-organiser
+Version: 0.1.0
+Summary: CLI tool for musical directors to classify and organise audio stem exports by instrument category.
+Author-email: Alex Hollingsworth <alex@hsoundworks.co.uk>
+License: MIT
+Project-URL: Homepage, https://github.com/alex-hollingsworth1/setlist_and_stem_organiser
+Project-URL: Issues, https://github.com/alex-hollingsworth1/setlist_and_stem_organiser/issues
+Keywords: audio,music,stems,ableton,playback,musical-director,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Setlist Organiser
+
+CLI tool for classifying audio stem filenames into categories and organising them into folder structure via copy or move operations.
+
+## What it does
+
+- Scans a source folder for audio files
+- Classifies each file by filename keywords (e.g. `DRUMS`, `BASS`, `VOX`)
+- Copies or moves files to `OUTPUT_ROOT/<CATEGORY>/...`
+- Supports dry-run, recursive scan, custom keyword config, and interactive review for `OTHER` files
+
+## Requirements
+
+- Python `>=3.11`
+
+## Install
+
+From the project root:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+This exposes the command:
+
+```bash
+setlist-organiser --help
+```
+
+## Basic usage
+
+```bash
+setlist-organiser SOURCE_DIR OUTPUT_ROOT
+```
+
+Example:
+
+```bash
+setlist-organiser ../../AUDIO_FILES_FOR_TESTING output
+```
+
+For paths with spaces, quote them:
+
+```bash
+setlist-organiser "/path/with spaces/Stems '24" output
+```
+
+## Common flags
+
+- `--dry-run`  
+  Show what would be copied without writing files.
+- `--quiet`  
+  Suppress per-file listing.
+- `--summary-only`  
+  Print category counts.
+- `--show-other`  
+  Print files currently classified as `OTHER`.
+- `--recursive`  
+  Scan nested folders.
+- `--config PATH`  
+  Load extra keyword mappings from a JSON config file.
+- `--review`  
+  Interactively review files in `OTHER` before execution.
+- `--move`  
+  Move files instead of copying them.
+
+## Interactive review mode
+
+Use review mode to handle uncertain files before copying:
+
+```bash
+setlist-organiser SOURCE_DIR OUTPUT_ROOT --review
+```
+
+For each `OTHER` file:
+
+- Press `Enter` to keep as `OTHER`
+- Type a category name (e.g. `DRUMS`, `VOX`, `KEYS`) to reassign
+- Type `s` to skip the file
+
+## Config file format
+
+Config adds extra keywords per category (it does not remove built-in defaults).
+
+Example `test_config.json`:
+
+```json
+{
+  "keywords": {
+    "DRUMS": ["room", "hh"],
+    "VOX": ["adlib_fx"]
+  }
+}
+```
+
+Run with config:
+
+```bash
+setlist-organiser SOURCE_DIR OUTPUT_ROOT --config test_config.json
+```
+
+## Move mode
+
+Use move mode when you want files relocated from source to destination:
+
+```bash
+setlist-organiser SOURCE_DIR OUTPUT_ROOT --move
+```
+
+Preview move operations without changing files:
+
+```bash
+setlist-organiser SOURCE_DIR OUTPUT_ROOT --move --dry-run
+```
+
+## Output behavior
+
+- `--dry-run`: no files are copied or moved
+- normal run: files are copied by default (metadata-preserving copy)
+- `--move`: files are moved instead of copied
+- destination collisions are suffixed (`_2`, `_3`, ...)
+
+## Development
+
+Run tests:
+
+```bash
+pytest -v
+```
+
+Or use Makefile shortcuts:
+
+```bash
+make test
+make dry-run
+make move-dry
+make review
+make summary
+```

setlist_organiser-0.1.0/README.md

@@ -0,0 +1,141 @@
+# Setlist Organiser
+
+CLI tool for classifying audio stem filenames into categories and organising them into folder structure via copy or move operations.
+
+## What it does
+
+- Scans a source folder for audio files
+- Classifies each file by filename keywords (e.g. `DRUMS`, `BASS`, `VOX`)
+- Copies or moves files to `OUTPUT_ROOT/<CATEGORY>/...`
+- Supports dry-run, recursive scan, custom keyword config, and interactive review for `OTHER` files
+
+## Requirements
+
+- Python `>=3.11`
+
+## Install
+
+From the project root:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+This exposes the command:
+
+```bash
+setlist-organiser --help
+```
+
+## Basic usage
+
+```bash
+setlist-organiser SOURCE_DIR OUTPUT_ROOT
+```
+
+Example:
+
+```bash
+setlist-organiser ../../AUDIO_FILES_FOR_TESTING output
+```
+
+For paths with spaces, quote them:
+
+```bash
+setlist-organiser "/path/with spaces/Stems '24" output
+```
+
+## Common flags
+
+- `--dry-run`  
+  Show what would be copied without writing files.
+- `--quiet`  
+  Suppress per-file listing.
+- `--summary-only`  
+  Print category counts.
+- `--show-other`  
+  Print files currently classified as `OTHER`.
+- `--recursive`  
+  Scan nested folders.
+- `--config PATH`  
+  Load extra keyword mappings from a JSON config file.
+- `--review`  
+  Interactively review files in `OTHER` before execution.
+- `--move`  
+  Move files instead of copying them.
+
+## Interactive review mode
+
+Use review mode to handle uncertain files before copying:
+
+```bash
+setlist-organiser SOURCE_DIR OUTPUT_ROOT --review
+```
+
+For each `OTHER` file:
+
+- Press `Enter` to keep as `OTHER`
+- Type a category name (e.g. `DRUMS`, `VOX`, `KEYS`) to reassign
+- Type `s` to skip the file
+
+## Config file format
+
+Config adds extra keywords per category (it does not remove built-in defaults).
+
+Example `test_config.json`:
+
+```json
+{
+  "keywords": {
+    "DRUMS": ["room", "hh"],
+    "VOX": ["adlib_fx"]
+  }
+}
+```
+
+Run with config:
+
+```bash
+setlist-organiser SOURCE_DIR OUTPUT_ROOT --config test_config.json
+```
+
+## Move mode
+
+Use move mode when you want files relocated from source to destination:
+
+```bash
+setlist-organiser SOURCE_DIR OUTPUT_ROOT --move
+```
+
+Preview move operations without changing files:
+
+```bash
+setlist-organiser SOURCE_DIR OUTPUT_ROOT --move --dry-run
+```
+
+## Output behavior
+
+- `--dry-run`: no files are copied or moved
+- normal run: files are copied by default (metadata-preserving copy)
+- `--move`: files are moved instead of copied
+- destination collisions are suffixed (`_2`, `_3`, ...)
+
+## Development
+
+Run tests:
+
+```bash
+pytest -v
+```
+
+Or use Makefile shortcuts:
+
+```bash
+make test
+make dry-run
+make move-dry
+make review
+make summary
+```

setlist_organiser-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "setlist-organiser"
+version = "0.1.0"
+description = "CLI tool for musical directors to classify and organise audio stem exports by instrument category."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+authors = [
+    {name = "Alex Hollingsworth", email = "alex@hsoundworks.co.uk"}
+]
+license = {text = "MIT"}
+keywords = ["audio", "music", "stems", "ableton", "playback", "musical-director", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio",
+]
+
+[project.urls]
+Homepage = "https://github.com/alex-hollingsworth1/setlist_and_stem_organiser"
+Issues = "https://github.com/alex-hollingsworth1/setlist_and_stem_organiser/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[project.scripts]
+setlist-organiser = "setlist_organiser.cli:main"

setlist_organiser-0.1.0/setup.cfg

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

setlist_organiser-0.1.0/src/setlist_organiser/classifier.py

@@ -0,0 +1,307 @@
+"""Filename classification logic for setlist organiser."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import re
+
+from .models import Category, ClassifiedFile
+
+_SEPARATOR_RE = re.compile(r"[^a-z0-9]+")
+_SPACE_RE = re.compile(r"\s+")
+_DIGIT_LETTER_RE = re.compile(r"(\d)([a-zA-Z])")
+_LETTER_DIGIT_RE = re.compile(r"([a-zA-Z])(\d)")
+
+
+@dataclass(frozen=True, slots=True)
+class _CategoryMatch:
+    """Internal match candidate for potential category resolution."""
+
+    category: Category
+    matched_keyword: str
+
+
+CATEGORY_KEYWORDS: dict[Category, tuple[str, ...]] = {
+    Category.PERC: (
+        "perc",
+        "percussion",
+        "shaker",
+        "tambourine",
+        "tamb",
+        "conga",
+        "congas",
+        "bongo",
+        "bongos",
+        "clap",
+        "claps",
+        "stomp",
+        "stomps",
+        "bells",
+        "triangle",
+        "hit",
+        "hits",
+    ),
+    Category.DRUMS: (
+        "drum",
+        "drums",
+        "kit",
+        "snare",
+        "snares",
+        "snr",
+        "kick",
+        "kicks",
+        "kck",
+        "kik",
+        "toms",
+        "hihat",
+        "hi hat",
+        "hh",
+        "cym",
+        "ride",
+        "crash",
+        "overhead",
+        "oh",
+        "rimshot",
+        "rim",
+    ),
+    Category.BASS: (
+        "bass",
+        "bassgtr",
+        "bass guitar",
+    ),
+    Category.SUB: (
+        "sub",
+        "808",
+        "low end",
+        "sub bass",
+    ),
+    Category.KEYS: (
+        "keys",
+        "key",
+        "piano",
+        "rhodes",
+        "wurli",
+        "organ",
+        "synth",
+        "pad",
+        "arp",
+        "synths",
+        "synth pad",
+        "sine",
+        "saw",
+        "square",
+        "sc",
+        "sidechain"
+    ),
+    Category.GTR: (
+        "gtr",
+        "guitar",
+        "acoustic",
+        "electric",
+        "lead gtr",
+        "rhythm gtr",
+    ),
+    Category.VOX: (
+        "vox",
+        "voc",
+        "vocal",
+        "lead vox",
+        "lead vocal",
+        "vocoder",
+        "adlib",
+        "adlibs",
+        "ad libs",
+        "double",
+        "dbl",
+        "doubles",
+        "lv",
+    ),
+    Category.BVS: (
+        "bv",
+        "bvs",
+        "backing vocal",
+        "backing vox",
+        "harmony",
+        "choir",
+        "stack",
+        "gang vox",
+        "harmonies",
+        "harms",
+    ),
+    Category.FX: (
+        "fx",
+        "sfx",
+        "impact",
+        "riser",
+        "sweep",
+        "transition",
+        "verb",
+        "reverb",
+        "rverb",
+        "rvb",
+        "delay",
+        "dly",
+        "throw",
+        "beep",
+        "noise",
+        "white noise",
+        "atmos",
+        "atmosphere"
+    ),
+    Category.CLICK: (
+        "click",
+        "metronome",
+        "metro",
+        "clk",
+    ),
+    Category.CUES: (
+        "cue",
+        "cues",
+        "guide",
+        "guide vox",
+        "guide vocal",
+        "talkback",
+        "count in",
+        "countin",
+    ),
+    Category.STRINGS: (
+        "strings",
+        "string",
+        "violin",
+        "viola",
+        "cello",
+    ),
+    Category.BRASS: (
+        "brass",
+        "trumpet",
+        "trombone",
+        "tuba",
+        "horn",
+        "horns",
+    ),
+    Category.WOODWIND: (
+        "woodwind",
+        "flute",
+        "oboe",
+        "clarinet",
+        "saxophone",
+        "bassoon",
+    ),
+    Category.OTHER: (),
+}
+
+
+CATEGORY_PRIORITY: tuple[Category, ...] = (
+    Category.CLICK,
+    Category.CUES,
+    Category.BVS,
+    Category.VOX,
+    Category.FX,
+    Category.DRUMS,
+    Category.PERC,
+    Category.SUB,
+    Category.BASS,
+    Category.KEYS,
+    Category.GTR,
+    Category.STRINGS,
+    Category.BRASS,
+    Category.WOODWIND,
+    Category.OTHER,
+)
+
+
+def _normalize_name(name: str) -> str:
+    name = _DIGIT_LETTER_RE.sub(r"\1 \2", name)
+    name = _LETTER_DIGIT_RE.sub(r"\1 \2", name)
+    cleaned = _SEPARATOR_RE.sub(" ", name.lower())
+    return _SPACE_RE.sub(" ", cleaned).strip()
+
+
+def _tokenize(normalized_name: str) -> set[str]:
+    if not normalized_name:
+        return set()
+    return set(normalized_name.split(" "))
+
+
+def _keyword_matches(
+    keyword: str, normalized_name: str, tokens: set[str]
+) -> bool:
+    normalized_keyword = _normalize_name(keyword)
+    if not normalized_keyword:
+        return False
+    if " " in normalized_keyword:
+        return normalized_keyword in normalized_name
+    return normalized_keyword in tokens
+
+
+def _collect_candidate_matches(
+    name: str,
+    *,
+    keywords: dict[Category, tuple[str, ...]],
+) -> list[_CategoryMatch]:
+    normalized_name = _normalize_name(Path(name).stem)
+    tokens = _tokenize(normalized_name)
+    candidates: list[_CategoryMatch] = []
+
+    for category, keyword_tuple in keywords.items():
+        for keyword in keyword_tuple:
+            if _keyword_matches(keyword, normalized_name, tokens):
+                candidates.append(
+                    _CategoryMatch(category=category, matched_keyword=keyword)
+                )
+                break
+
+    return candidates
+
+
+def _resolve_single_category(
+    candidates: list[_CategoryMatch],
+    *,
+    priority: tuple[Category, ...],
+) -> _CategoryMatch:
+    if not candidates:
+        return _CategoryMatch(
+            category=Category.OTHER,
+            matched_keyword="",
+        )
+
+    candidate_by_category = {candidate.category: candidate for candidate in candidates}
+    for category in priority:
+        if category in candidate_by_category:
+            return candidate_by_category[category]
+
+    return _CategoryMatch(category=Category.OTHER, matched_keyword="")
+
+
+def classify_name(
+    name: str,
+    source: Path | None = None,
+    *,
+    keywords: dict[Category, tuple[str, ...]] | None = None,
+) -> ClassifiedFile:
+    """Classify a filename into a single category."""
+    source_path = source if source is not None else Path(name)
+    kw = CATEGORY_KEYWORDS if keywords is None else keywords
+    candidates = _collect_candidate_matches(name, keywords=kw)
+    resolved = _resolve_single_category(candidates, priority=CATEGORY_PRIORITY)
+
+    return ClassifiedFile(
+        source=source_path,
+        category=resolved.category,
+        matched_keyword=resolved.matched_keyword or None,
+    )
+
+
+def classify_path(
+    path: Path,
+    *,
+    keywords: dict[Category, tuple[str, ...]] | None = None,
+) -> ClassifiedFile:
+    """Classify a file path based on its name."""
+    return classify_name(name=path.name, source=path, keywords=keywords)
+
+
+def _get_candidate_matches(name: str) -> tuple[_CategoryMatch, ...]:
+    """Return all category candidates for future interactive resolution."""
+    return tuple(_collect_candidate_matches(name, keywords=CATEGORY_KEYWORDS))