breaks-machine 0.1.0__py3-none-any.whl

breaks_machine/__init__.py

@@ -0,0 +1,3 @@
+"""breaks-machine package."""
+
+__version__ = "0.1.0"

breaks_machine/cli.py

@@ -0,0 +1,190 @@
+"""Command-line interface for breaks-machine."""
+
+from pathlib import Path
+
+import click
+
+from .processor import (
+    ProcessingOptions,
+    is_audio_file,
+    parse_targets,
+    process_directory,
+    process_file,
+)
+from .stretcher import RubberbandNotFoundError, check_rubberband_installed
+
+
+@click.group()
+@click.version_option()
+def cli():
+    """breaks-machine: Time-stretch drum breaks to target BPMs."""
+    pass
+
+
+@cli.command()
+@click.argument("input_path", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "-t",
+    "--target",
+    type=float,
+    help="Single target BPM",
+)
+@click.option(
+    "--targets",
+    type=str,
+    help="Comma-separated target BPMs (e.g., 90,120,140)",
+)
+@click.option(
+    "-r",
+    "--range",
+    "range_spec",
+    type=str,
+    help="BPM range (e.g., 80-160)",
+)
+@click.option(
+    "-s",
+    "--step",
+    type=int,
+    default=10,
+    show_default=True,
+    help="Step size for range",
+)
+@click.option(
+    "-b",
+    "--bpm",
+    type=float,
+    help="Manual source BPM override",
+)
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(path_type=Path),
+    default=Path("./output"),
+    show_default=True,
+    help="Output directory",
+)
+@click.option(
+    "--sample-rate",
+    type=int,
+    help="Target sample rate (e.g., 44100, 48000)",
+)
+@click.option(
+    "--bit-depth",
+    type=click.Choice(["16", "24"]),
+    help="Target bit depth",
+)
+@click.option(
+    "--mono",
+    is_flag=True,
+    help="Convert to mono",
+)
+@click.option(
+    "-w",
+    "--warn",
+    is_flag=True,
+    help="Warn if detected BPM differs from filename",
+)
+@click.option(
+    "--crispness",
+    type=click.IntRange(0, 6),
+    default=5,
+    show_default=True,
+    help="Rubberband crispness (0-6, higher preserves transients)",
+)
+def stretch(
+    input_path: Path,
+    target: float | None,
+    targets: str | None,
+    range_spec: str | None,
+    step: int,
+    bpm: float | None,
+    output: Path,
+    sample_rate: int | None,
+    bit_depth: str | None,
+    mono: bool,
+    warn: bool,
+    crispness: int,
+):
+    """
+    Time-stretch audio file(s) to target BPM(s).
+
+    INPUT_PATH can be a single audio file or a directory containing audio files.
+
+    Examples:
+
+        # Single file, single target
+        breaks-machine stretch break.wav --target 140
+
+        # Multiple targets
+        breaks-machine stretch break.wav --targets 90,120,140
+
+        # Range of targets
+        breaks-machine stretch break.wav --range 80-160 --step 10
+
+        # Batch process directory
+        breaks-machine stretch ./breaks/ --target 140
+
+        # With format conversion
+        breaks-machine stretch break.wav -t 140 --sample-rate 44100 --mono
+    """
+    # Check rubberband is installed
+    try:
+        check_rubberband_installed()
+    except RubberbandNotFoundError as e:
+        raise click.ClickException(str(e)) from None
+
+    # Parse targets
+    try:
+        target_bpms = parse_targets(target, targets, range_spec, step)
+    except ValueError as e:
+        raise click.ClickException(str(e)) from None
+
+    # Build options
+    options = ProcessingOptions(
+        manual_bpm=bpm,
+        sample_rate=sample_rate,
+        bit_depth=int(bit_depth) if bit_depth else None,
+        mono=mono,
+        warn=warn,
+        crispness=crispness,
+    )
+
+    click.echo(f"Target BPM(s): {', '.join(str(int(t)) for t in target_bpms)}")
+    click.echo(f"Output directory: {output}")
+    click.echo()
+
+    try:
+        if input_path.is_dir():
+            outputs = process_directory(
+                input_path,
+                target_bpms,
+                output,
+                options,
+                echo=click.echo,
+            )
+        elif is_audio_file(input_path):
+            outputs = process_file(
+                input_path,
+                target_bpms,
+                output,
+                options,
+                echo=click.echo,
+            )
+        else:
+            raise click.ClickException(
+                f"Unsupported file type: {input_path.suffix}. Supported: .wav, .flac"
+            )
+    except Exception as e:
+        raise click.ClickException(str(e)) from None
+
+    click.echo()
+    click.echo(f"Created {len(outputs)} file(s)")
+
+
+def main():
+    """Entry point for the CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

breaks_machine/converter.py

@@ -0,0 +1,95 @@
+"""Audio format conversion utilities."""
+
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+
+# Map bit depth to soundfile subtype
+BIT_DEPTH_TO_SUBTYPE = {
+    16: "PCM_16",
+    24: "PCM_24",
+    32: "PCM_32",
+}
+
+
+def convert_audio(
+    input_path: Path,
+    output_path: Path | None = None,
+    sample_rate: int | None = None,
+    bit_depth: int | None = None,
+    mono: bool = False,
+) -> Path:
+    """
+    Convert audio file format, sample rate, bit depth, and/or channels.
+
+    Args:
+        input_path: Path to input audio file
+        output_path: Path for output file (defaults to overwriting input)
+        sample_rate: Target sample rate in Hz (e.g., 44100, 48000)
+        bit_depth: Target bit depth (16 or 24)
+        mono: Convert to mono if True
+
+    Returns:
+        Path to the output file
+    """
+    if output_path is None:
+        output_path = input_path
+
+    # Load audio
+    y, sr = sf.read(input_path)
+    input_info = sf.info(input_path)
+
+    # Track if any conversion is needed
+    needs_conversion = False
+
+    # Resample if needed
+    if sample_rate is not None and sample_rate != sr:
+        needs_conversion = True
+        # Use soxr for high-quality resampling (installed with librosa)
+        import soxr
+
+        y = soxr.resample(y, sr, sample_rate)
+        sr = sample_rate
+
+    # Convert to mono if needed
+    if mono and len(y.shape) > 1 and y.shape[1] > 1:
+        needs_conversion = True
+        y = np.mean(y, axis=1)
+
+    # Determine output subtype
+    if bit_depth is not None:
+        needs_conversion = True
+        subtype = BIT_DEPTH_TO_SUBTYPE.get(bit_depth)
+        if subtype is None:
+            raise ValueError(f"Unsupported bit depth: {bit_depth}. Use 16, 24, or 32.")
+    else:
+        subtype = input_info.subtype
+
+    # Only write if conversion was needed or output path differs
+    if needs_conversion or output_path != input_path:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        sf.write(output_path, y, sr, subtype=subtype)
+
+    return output_path
+
+
+def get_audio_info(file_path: Path) -> dict:
+    """
+    Get audio file information.
+
+    Args:
+        file_path: Path to audio file
+
+    Returns:
+        Dictionary with audio properties
+    """
+    info = sf.info(file_path)
+    return {
+        "sample_rate": info.samplerate,
+        "channels": info.channels,
+        "frames": info.frames,
+        "duration": info.duration,
+        "format": info.format,
+        "subtype": info.subtype,
+    }

breaks_machine/detector.py

@@ -0,0 +1,194 @@
+"""BPM detection from filenames and audio analysis."""
+
+import re
+from collections.abc import Callable
+from pathlib import Path
+
+import librosa
+
+
+class BPMDetectionError(Exception):
+    """Raised when BPM cannot be determined."""
+
+    pass
+
+
+def parse_bpm_from_filename(file_path: Path) -> float | None:
+    """
+    Extract BPM from filename using common naming conventions.
+
+    Matches patterns like:
+    - amen_170.wav -> 170
+    - break-85bpm.flac -> 85
+    - think_120_BPM.wav -> 120
+    - funky_90-bpm.wav -> 90
+    - drum_loop_140BPM.wav -> 140
+
+    Returns None if no BPM found in filename.
+    """
+    filename = file_path.stem
+
+    # Pattern: number followed by optional separator and "bpm" (case insensitive)
+    # e.g., "85bpm", "85-bpm", "85_BPM", "85 bpm"
+    pattern_with_bpm = r"(\d{2,3})[\s_-]?bpm"
+    match = re.search(pattern_with_bpm, filename, re.IGNORECASE)
+    if match:
+        return float(match.group(1))
+
+    # Pattern: underscore/hyphen followed by 2-3 digit number at end or before extension
+    # e.g., "amen_170", "break-85"
+    pattern_trailing = r"[_-](\d{2,3})(?:[_-]|$)"
+    match = re.search(pattern_trailing, filename)
+    if match:
+        bpm = float(match.group(1))
+        # Sanity check: BPM should be in reasonable range (50-250)
+        if 50 <= bpm <= 250:
+            return bpm
+
+    return None
+
+
+def detect_bpm_with_librosa(file_path: Path) -> float:
+    """
+    Detect BPM using librosa's beat tracking with multiple strategies.
+
+    Uses multiple tempo priors and subdivision correction to improve accuracy
+    on complex breakbeats.
+
+    Returns the estimated BPM.
+    """
+    y, sr = librosa.load(file_path, sr=None)
+
+    # Strategy 1: Try multiple starting priors
+    # Default (120), medium (140), and high (170) to cover different tempo ranges
+    priors = [None, 140, 170]
+    all_candidates = []
+
+    for prior in priors:
+        if prior is None:
+            tempo = librosa.feature.tempo(y=y, sr=sr, aggregate=None)
+        else:
+            tempo = librosa.feature.tempo(y=y, sr=sr, start_bpm=prior, aggregate=None)
+
+        # Extract candidates
+        if hasattr(tempo, "__len__") and len(tempo) > 0:
+            all_candidates.extend([float(t) for t in tempo[:4]])
+        else:
+            all_candidates.append(float(tempo))
+
+    # Remove duplicates
+    candidates = sorted(set(all_candidates))
+
+    # Strategy 2: For each candidate, consider common subdivision relationships
+    # Breakbeat detection often finds subdivisions (2/3, 1/2, 3/4 time)
+    expanded_candidates = []
+    for bpm in candidates:
+        expanded_candidates.append(bpm)
+        expanded_candidates.append(bpm * 2)  # Double-time (2x)
+        expanded_candidates.append(bpm * 1.5)  # 3/2 time
+        expanded_candidates.append(bpm * (4 / 3))  # 4/3 time
+        expanded_candidates.append(bpm / 1.5)  # 2/3 time (detected too high)
+
+    # Remove duplicates and filter to reasonable range (80-200 BPM)
+    valid_candidates = sorted(set(bpm for bpm in expanded_candidates if 80 <= bpm <= 200))
+
+    if not valid_candidates:
+        # Fallback to original candidate if nothing in range
+        return candidates[0] if candidates else 120.0
+
+    # Strategy 3: Prefer direct detections over derived subdivisions
+    # Group candidates by how they were obtained
+    direct_detections = [bpm for bpm in candidates if 80 <= bpm <= 200]
+
+    if direct_detections:
+        # Prefer candidates that were directly detected (not subdivisions)
+        # Return the one closest to the common breakbeat range (140-180)
+        target = 160
+        best = min(direct_detections, key=lambda x: abs(x - target))
+        return best
+    else:
+        # Fall back to derived candidates if no direct detection in range
+        target = 160
+        best = min(valid_candidates, key=lambda x: abs(x - target))
+        return best
+
+
+def bpms_match(bpm1: float, bpm2: float, tolerance: float = 3.0) -> bool:
+    """
+    Check if two BPMs match, accounting for 2x/0.5x detection differences.
+
+    Args:
+        bpm1: First BPM value
+        bpm2: Second BPM value
+        tolerance: Acceptable difference in BPM (default 3.0)
+
+    Returns:
+        True if BPMs match (including half/double time variants)
+    """
+    # Direct match
+    if abs(bpm1 - bpm2) <= tolerance:
+        return True
+
+    # Check half time (bpm2 is half of bpm1)
+    if abs(bpm1 - bpm2 * 2) <= tolerance:
+        return True
+
+    # Check double time (bpm2 is double of bpm1)
+    if abs(bpm1 * 2 - bpm2) <= tolerance:
+        return True
+
+    return False
+
+
+def get_source_bpm(
+    file_path: Path,
+    manual_bpm: float | None = None,
+    warn: bool = False,
+    warn_callback: Callable[[str], None] | None = None,
+) -> float:
+    """
+    Determine source BPM using priority: manual > filename > auto-detect.
+
+    Args:
+        file_path: Path to audio file
+        manual_bpm: User-specified BPM override (highest priority)
+        warn: Whether to warn if detected BPM differs from filename
+        warn_callback: Function to call with warning message
+
+    Returns:
+        Detected or specified BPM
+
+    Raises:
+        BPMDetectionError: If no BPM source available
+    """
+    # 1. Manual override wins
+    if manual_bpm is not None:
+        return manual_bpm
+
+    # 2. Try filename parsing
+    filename_bpm = parse_bpm_from_filename(file_path)
+
+    # 3. Auto-detect as fallback (or for validation)
+    detected_bpm = None
+    if filename_bpm is None or warn:
+        try:
+            detected_bpm = detect_bpm_with_librosa(file_path)
+        except Exception as e:
+            if filename_bpm is None:
+                raise BPMDetectionError(f"Could not determine BPM for {file_path}: {e}") from e
+
+    # Return filename BPM if available
+    if filename_bpm is not None:
+        # Warn if detection differs (ignoring 2x/0.5x)
+        if warn and detected_bpm is not None and warn_callback:
+            if not bpms_match(filename_bpm, detected_bpm):
+                warn_callback(
+                    f"Filename suggests {filename_bpm} BPM, but detected {detected_bpm:.1f} BPM"
+                )
+        return filename_bpm
+
+    # Fall back to detected BPM
+    if detected_bpm is not None:
+        return detected_bpm
+
+    raise BPMDetectionError(f"Could not determine BPM for {file_path}")

breaks_machine/processor.py

@@ -0,0 +1,206 @@
+"""Pipeline orchestration for processing drum breaks."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from .converter import convert_audio
+from .detector import get_source_bpm
+from .stretcher import stretch_to_bpm
+
+# Supported audio extensions
+SUPPORTED_EXTENSIONS = {".wav", ".flac"}
+
+
+def _noop_echo(_: str) -> None:
+    """No-op function for echo when none is provided."""
+    pass
+
+
+@dataclass
+class ProcessingOptions:
+    """Options for audio processing."""
+
+    manual_bpm: float | None = None
+    sample_rate: int | None = None
+    bit_depth: int | None = None
+    mono: bool = False
+    warn: bool = False
+    crispness: int = 5
+
+
+def is_audio_file(path: Path) -> bool:
+    """Check if a path is a supported audio file."""
+    return path.is_file() and path.suffix.lower() in SUPPORTED_EXTENSIONS
+
+
+def generate_output_path(
+    input_path: Path,
+    output_dir: Path,
+    target_bpm: float,
+) -> Path:
+    """
+    Generate output path following the naming convention.
+
+    Structure: output_dir/{filename}/{filename}_{target_bpm}bpm.{ext}
+    """
+    stem = input_path.stem
+    ext = input_path.suffix
+    folder = output_dir / stem
+    filename = f"{stem}_{int(target_bpm)}bpm{ext}"
+    return folder / filename
+
+
+def process_file(
+    input_path: Path,
+    targets: list[float],
+    output_dir: Path,
+    options: ProcessingOptions,
+    echo: Callable[[str], None] | None = None,
+) -> list[Path]:
+    """
+    Process a single audio file to multiple target BPMs.
+
+    Args:
+        input_path: Path to input audio file
+        targets: List of target BPMs
+        output_dir: Base output directory
+        options: Processing options
+        echo: Optional callback for status messages
+
+    Returns:
+        List of created output file paths
+    """
+    if echo is None:
+        echo = _noop_echo
+
+    # Detect source BPM
+    echo(f"Detecting BPM for {input_path.name}...")
+    source_bpm = get_source_bpm(
+        input_path,
+        manual_bpm=options.manual_bpm,
+        warn=options.warn,
+        warn_callback=echo,
+    )
+    echo(f"  Source BPM: {source_bpm}")
+
+    output_paths = []
+
+    for target_bpm in targets:
+        output_path = generate_output_path(input_path, output_dir, target_bpm)
+        echo(f"  Stretching to {int(target_bpm)} BPM -> {output_path}")
+
+        # Time stretch
+        stretch_to_bpm(
+            input_path,
+            output_path,
+            source_bpm,
+            target_bpm,
+            crispness=options.crispness,
+        )
+
+        # Apply format conversion if any options specified
+        if options.sample_rate or options.bit_depth or options.mono:
+            convert_audio(
+                output_path,
+                output_path,
+                sample_rate=options.sample_rate,
+                bit_depth=options.bit_depth,
+                mono=options.mono,
+            )
+
+        output_paths.append(output_path)
+
+    return output_paths
+
+
+def process_directory(
+    input_dir: Path,
+    targets: list[float],
+    output_dir: Path,
+    options: ProcessingOptions,
+    echo: Callable[[str], None] | None = None,
+) -> list[Path]:
+    """
+    Process all audio files in a directory.
+
+    Args:
+        input_dir: Directory containing audio files
+        targets: List of target BPMs
+        output_dir: Base output directory
+        options: Processing options
+        echo: Optional callback for status messages
+
+    Returns:
+        List of all created output file paths
+    """
+    if echo is None:
+        echo = _noop_echo
+
+    # Find all audio files
+    audio_files = sorted([f for f in input_dir.iterdir() if is_audio_file(f)])
+
+    if not audio_files:
+        raise ValueError(f"No audio files found in {input_dir}")
+
+    echo(f"Found {len(audio_files)} audio file(s)")
+
+    all_outputs = []
+
+    for audio_file in audio_files:
+        outputs = process_file(audio_file, targets, output_dir, options, echo)
+        all_outputs.extend(outputs)
+
+    return all_outputs
+
+
+def parse_targets(
+    target: float | None,
+    targets: str | None,
+    range_spec: str | None,
+    step: int,
+) -> list[float]:
+    """
+    Parse target BPM specifications into a list of BPMs.
+
+    Args:
+        target: Single target BPM
+        targets: Comma-separated target BPMs
+        range_spec: Range specification (e.g., "80-160")
+        step: Step size for range
+
+    Returns:
+        List of target BPMs
+
+    Raises:
+        ValueError: If no valid targets specified
+    """
+    result = []
+
+    if target is not None:
+        result.append(target)
+
+    if targets is not None:
+        for t in targets.split(","):
+            result.append(float(t.strip()))
+
+    if range_spec is not None:
+        parts = range_spec.split("-")
+        if len(parts) != 2:
+            raise ValueError(f"Invalid range format: {range_spec}. Use 'start-end'.")
+        start = int(parts[0])
+        end = int(parts[1])
+        result.extend(float(bpm) for bpm in range(start, end + 1, step))
+
+    if not result:
+        raise ValueError("No target BPM specified. Use --target, --targets, or --range.")
+
+    # Remove duplicates while preserving order
+    seen = set()
+    unique = []
+    for bpm in result:
+        if bpm not in seen:
+            seen.add(bpm)
+            unique.append(bpm)
+
+    return unique

breaks_machine/stretcher.py

@@ -0,0 +1,116 @@
+"""Time-stretching audio using rubberband."""
+
+import shutil
+import sys
+from pathlib import Path
+
+import pyrubberband
+import soundfile as sf
+
+
+class RubberbandNotFoundError(Exception):
+    """Raised when rubberband CLI is not installed."""
+
+    pass
+
+
+def check_rubberband_installed() -> None:
+    """
+    Verify that rubberband CLI is installed and accessible.
+
+    Raises:
+        RubberbandNotFoundError: If rubberband is not found with install instructions.
+    """
+    if shutil.which("rubberband") is None:
+        platform = sys.platform
+        if platform == "darwin":
+            install_cmd = "brew install rubberband"
+        elif platform.startswith("linux"):
+            install_cmd = "sudo apt-get install rubberband-cli"
+        elif platform == "win32":
+            install_cmd = "Download from https://breakfastquay.com/rubberband/"
+        else:
+            install_cmd = "See https://breakfastquay.com/rubberband/"
+
+        raise RubberbandNotFoundError(
+            f"rubberband CLI not found. Install it with:\n  {install_cmd}"
+        )
+
+
+def calculate_stretch_ratio(source_bpm: float, target_bpm: float) -> float:
+    """
+    Calculate the time stretch ratio to convert from source to target BPM.
+
+    Args:
+        source_bpm: Original tempo in BPM
+        target_bpm: Desired tempo in BPM
+
+    Returns:
+        Stretch ratio for pyrubberband (>1 means faster/shorter, <1 means slower/longer)
+    """
+    # pyrubberband rate: >1 = faster (shorter duration), <1 = slower (longer duration)
+    # To go from 170 BPM to 85 BPM (slower), we need rate = 85/170 = 0.5
+    # To go from 85 BPM to 170 BPM (faster), we need rate = 170/85 = 2.0
+    return target_bpm / source_bpm
+
+
+def stretch_audio(
+    input_path: Path,
+    output_path: Path,
+    ratio: float,
+    crispness: int = 5,
+) -> None:
+    """
+    Time-stretch audio file using rubberband.
+
+    Args:
+        input_path: Path to input audio file
+        output_path: Path for output audio file
+        ratio: Time stretch ratio (>1 = slower, <1 = faster)
+        crispness: Rubberband crispness setting (0-6, default 5 for drums)
+                   Higher values preserve transients better.
+    """
+    # Load audio
+    y, sr = sf.read(input_path)
+
+    # pyrubberband expects mono or stereo as (samples,) or (samples, channels)
+    # soundfile returns (samples, channels) for stereo, (samples,) for mono
+
+    # Map crispness to pyrubberband options
+    # Crispness 5 = "--crispness 5" which is good for drums
+    # pyrubberband uses rbargs as a dict
+    rbargs = {"--crispness": str(crispness)}
+
+    # Time stretch
+    y_stretched = pyrubberband.time_stretch(y, sr, ratio, rbargs=rbargs)
+
+    # Ensure output directory exists
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Determine subtype based on input file format
+    input_info = sf.info(input_path)
+    subtype = input_info.subtype
+
+    # Write output with same format as input
+    sf.write(output_path, y_stretched, sr, subtype=subtype)
+
+
+def stretch_to_bpm(
+    input_path: Path,
+    output_path: Path,
+    source_bpm: float,
+    target_bpm: float,
+    crispness: int = 5,
+) -> None:
+    """
+    Convenience function to stretch audio from source BPM to target BPM.
+
+    Args:
+        input_path: Path to input audio file
+        output_path: Path for output audio file
+        source_bpm: Original tempo in BPM
+        target_bpm: Desired tempo in BPM
+        crispness: Rubberband crispness setting (0-6, default 5 for drums)
+    """
+    ratio = calculate_stretch_ratio(source_bpm, target_bpm)
+    stretch_audio(input_path, output_path, ratio, crispness)

breaks_machine-0.1.0.dist-info/METADATA

@@ -0,0 +1,344 @@
+Metadata-Version: 2.4
+Name: breaks-machine
+Version: 0.1.0
+Summary: Time-stretch drum breaks to target BPMs with automatic tempo detection
+Requires-Python: >=3.13
+Requires-Dist: click>=8.3.1
+Requires-Dist: librosa>=0.11.0
+Requires-Dist: pyrubberband>=0.4.0
+Requires-Dist: soundfile>=0.13.1
+Description-Content-Type: text/markdown
+
+# breaks-machine
+
+Time-stretch drum breaks to target BPMs while preserving transient quality.
+
+Perfect for preparing drum breaks for hardware samplers, live performance, or production workflows where you need breaks at specific tempos.
+
+## Features
+
+- **Automatic BPM Detection**: Intelligently detects tempo from filename patterns or uses librosa for audio analysis
+- **Multiple Target Modes**: Stretch to single BPM, multiple targets, or ranges with custom steps
+- **Batch Processing**: Process entire directories of breaks in one command
+- **High-Quality Stretching**: Uses Rubberband with crispness=5 optimized for transient preservation
+- **Format Conversion**: Optional sample rate, bit depth, and channel conversion
+- **Smart Detection**: Multi-strategy BPM detection with subdivision correction for complex breakbeats
+
+## Requirements
+
+### System Dependencies
+
+**Rubberband** is required for time-stretching:
+
+**macOS:**
+```bash
+brew install rubberband
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt-get install rubberband-cli libsndfile1 ffmpeg
+```
+
+**Windows:**
+Download Rubberband from [https://breakfastquay.com/rubberband/](https://breakfastquay.com/rubberband/) and add to PATH.
+
+### Python
+
+Python 3.13+ required.
+
+## Installation
+
+**With uv (recommended):**
+```bash
+uv tool install breaks-machine
+```
+
+**With pip:**
+```bash
+pip install breaks-machine
+```
+
+**From source:**
+```bash
+git clone https://github.com/yourusername/breaks-machine.git
+cd breaks-machine
+uv sync
+```
+
+## Quick Start
+
+### Single File, Single Target
+
+Stretch a break to 140 BPM:
+```bash
+breaks-machine stretch amen_170.wav --target 140
+```
+
+Output: `output/amen_170/amen_170_140bpm.wav`
+
+### Multiple Targets
+
+Create versions at different BPMs:
+```bash
+breaks-machine stretch amen_170.wav --targets 90,120,140,160
+```
+
+Output:
+```
+output/amen_170/
+├── amen_170_90bpm.wav
+├── amen_170_120bpm.wav
+├── amen_170_140bpm.wav
+└── amen_170_160bpm.wav
+```
+
+### BPM Range
+
+Generate versions across a range:
+```bash
+breaks-machine stretch break.wav --range 80-160 --step 10
+```
+
+Creates versions at 80, 90, 100, ..., 160 BPM.
+
+### Batch Processing
+
+Process an entire directory:
+```bash
+breaks-machine stretch ./breaks/ --target 140 --output ./processed/
+```
+
+### With Manual BPM Override
+
+If auto-detection fails or you know the correct tempo:
+```bash
+breaks-machine stretch break.wav --bpm 175 --target 140
+```
+
+## CLI Reference
+
+```
+breaks-machine stretch INPUT_PATH [OPTIONS]
+```
+
+### Arguments
+
+- `INPUT_PATH`: Path to audio file (.wav, .flac) or directory containing audio files
+
+### Options
+
+**Target Specification** (required, choose one):
+- `-t, --target BPM`: Single target BPM
+- `--targets BPM,BPM,...`: Comma-separated target BPMs
+- `-r, --range START-END`: BPM range with optional step
+
+**BPM Detection**:
+- `-b, --bpm BPM`: Manual source BPM override
+- `-w, --warn`: Warn if detected BPM differs from filename
+
+**Output**:
+- `-o, --output DIR`: Output directory (default: `./output`)
+
+**Format Conversion**:
+- `--sample-rate HZ`: Target sample rate (e.g., 44100, 48000)
+- `--bit-depth {16,24}`: Target bit depth
+- `--mono`: Convert to mono
+
+**Stretching**:
+- `--crispness {0-6}`: Rubberband crispness (default: 5, higher preserves transients)
+- `-s, --step N`: Step size for range mode (default: 10)
+
+### Examples
+
+**Basic usage**:
+```bash
+# Stretch to single target
+breaks-machine stretch amen_170.wav -t 140
+
+# Multiple targets
+breaks-machine stretch break.wav --targets 90,120,140
+
+# Range with custom step
+breaks-machine stretch break.wav --range 100-140 --step 5
+```
+
+**With format conversion**:
+```bash
+# Convert to 44.1kHz mono 16-bit
+breaks-machine stretch break.wav -t 140 --sample-rate 44100 --bit-depth 16 --mono
+```
+
+**Batch processing**:
+```bash
+# Process directory
+breaks-machine stretch ./breaks/ -t 140 -o ./output/
+
+# With manual BPM for all files
+breaks-machine stretch ./breaks/ -t 140 --bpm 170
+```
+
+## How It Works
+
+### Architecture
+
+```
+Input Audio → BPM Detection → Time Stretching → Format Conversion → Output
+                    ↓                 ↓                  ↓
+              detector.py       stretcher.py      converter.py
+```
+
+### BPM Detection Priority
+
+1. **Manual Override** (`--bpm`): If specified, uses this value
+2. **Filename Parsing**: Looks for patterns like `amen_170.wav`, `break-140bpm.flac`
+3. **Auto-Detection**: Uses librosa with multi-strategy detection:
+   - Tries multiple tempo priors (120, 140, 170 BPM)
+   - Applies subdivision correction for complex breakbeats
+   - Prefers direct detections over derived subdivisions
+   - Biases toward common breakbeat range (140-180 BPM)
+
+### Rubberband Crispness
+
+The tool uses crispness=5 by default, which:
+- Preserves transients (drum hits)
+- Minimizes phase artifacts
+- Optimized for percussive material
+
+You can adjust with `--crispness {0-6}` (higher = more transient preservation).
+
+## Supported Formats
+
+- **Input**: WAV, FLAC
+- **Output**: Same format as input (or specify conversion options)
+
+## Development
+
+### Local Setup
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/yourusername/breaks-machine.git
+   cd breaks-machine
+   ```
+
+2. **Install system dependencies** (see Requirements above)
+
+3. **Install Python dependencies**:
+   ```bash
+   uv sync --group dev
+   ```
+
+4. **Run tests**:
+   ```bash
+   uv run pytest tests
+   ```
+
+### Using Devcontainer (Optional)
+
+For zero-friction setup with all dependencies pre-installed:
+
+1. **Install prerequisites**:
+   - [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+   - [VS Code](https://code.visualstudio.com/) with [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+2. **Copy devcontainer template**:
+   ```bash
+   cp -r .devcontainer-template .devcontainer
+   ```
+
+3. **Open in container**:
+   - VS Code → Command Palette → "Dev Containers: Reopen in Container"
+   - Wait for build (first time takes a few minutes)
+
+See [.devcontainer-template/README.md](.devcontainer-template/README.md) for details.
+
+### Running Tests
+
+```bash
+# All tests
+uv run pytest tests
+
+# With coverage
+uv run pytest tests --cov=src/breaks_machine
+
+# Specific test file
+uv run pytest tests/test_detector.py -v
+```
+
+### Code Quality
+
+```bash
+# Format code
+uvx ruff format
+
+# Lint code
+uvx ruff check --fix
+
+# Type checking (if added)
+uvx mypy src/
+```
+
+### Manual Testing
+
+The repository includes test breaks in the `breaks/` directory:
+```bash
+# Test with real breaks
+uv run breaks-machine stretch breaks/FR_Drum_Loop_160.wav -t 140
+```
+
+### Project Structure
+
+```
+src/breaks_machine/
+├── cli.py          # Click-based CLI entry point
+├── detector.py     # BPM detection (filename + librosa)
+├── stretcher.py    # Rubberband wrapper
+├── converter.py    # Format conversion
+└── processor.py    # Processing pipeline
+
+tests/
+├── test_cli.py
+├── test_detector.py
+├── test_stretcher.py
+├── test_converter.py
+└── test_processor.py
+```
+
+## Technical Details
+
+### Dependencies
+
+- **click**: CLI framework
+- **librosa**: Audio analysis and BPM detection
+- **pyrubberband**: Python wrapper for Rubberband
+- **soundfile**: Audio I/O for WAV/FLAC
+
+### System Requirements
+
+- **rubberband-cli**: Time-stretching engine
+- **libsndfile1**: Audio file I/O library
+- **ffmpeg**: Audio codec support
+
+See the Requirements section for platform-specific installation instructions.
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `uv run pytest tests`
+5. Format code: `uvx ruff format`
+6. Submit a pull request
+
+## License
+
+[Add your license here]
+
+## Acknowledgments
+
+- **Rubberband**: Industry-standard time-stretching library
+- **librosa**: Audio analysis toolkit
+- Built with modern Python tooling (uv, ruff, pytest)

breaks_machine-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+breaks_machine/__init__.py,sha256=gHQTrdDrMhdLOz9EkSLbI049ROXV31KxtlWtXyFdlLE,53
+breaks_machine/cli.py,sha256=Qttj-QnIWtKksEP2M0Bn20-_py1DFrATABHXfRNkNtg,4301
+breaks_machine/converter.py,sha256=o6XfA1_hftoD6OrMlt-fGg9eBec7RbnUaJq_KGOKPLA,2497
+breaks_machine/detector.py,sha256=uiRabYUWkyJRXEfNQmTJw3n_lNF2X9nmJNI1tvpvAxQ,6281
+breaks_machine/processor.py,sha256=ZPA3IzYZrUEbNc4g33V9aq0Fo_Pbi45i5r8u2V72fdw,5299
+breaks_machine/stretcher.py,sha256=UFuNr2888INDcrONre21iQLekwGX4xrGcx5STPu_v-w,3609
+breaks_machine-0.1.0.dist-info/METADATA,sha256=2UcQaZxICsHTvPmRAdSXrV2WNz4p1A-5OkisUglwkFQ,8244
+breaks_machine-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+breaks_machine-0.1.0.dist-info/entry_points.txt,sha256=eNWJkeqXBEWh794-GFt12qIGag77LaMM1FQ8jqfvZak,59
+breaks_machine-0.1.0.dist-info/RECORD,,

breaks_machine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

breaks_machine-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+breaks-machine = breaks_machine.cli:main