# Retro Tape Tool Suite Architecture

## Goals

1. Accept retro-computer cassette dumps (initial focus: lsig.flac).
2. Perform aggressive time-base manipulation (up to 1e3) to expose digital patterns hidden in slowed/encoded audio.
3. Provide multiple complementary analysestime-domain, frequency-domain, pulse-shape, bitstream inferenceand export artifacts for further tooling (e.g., BBC Micro decoding utilities).

## High-Level Pipeline

FLAC/WAV input
    load & metadata capture
Channel conditioning (mono mix , DC removal, windowed normalization)
   
Time-base engines (resample, phase vocoder, zero-crossing stretch)
   
Analysis stages
    Time-domain pulse/edge detection
    Spectral overview (FFT, spectrogram, cepstrum)
    Autocorrelation & baud hints
    Bit-grid inference (adaptive thresholding)
    Export (WAV @ multiple speeds, CSV, PNG, JSON report)

Each stage emits diagnostics so users can iterate on parameter choices without re-running upstream work.

## Packages & Responsibilities

| Module | Responsibility |
| --- | --- |
| retro_tape_tools.audio_io | Lossless audio loading (FLAC via soundfile), metadata capture, WAV export helpers. |
| retro_tape_tools.preprocessing | Channel mixing, DC offset removal, dynamic-range normalization, band-pass filters. |
| retro_tape_tools.timebase | Speed manipulation engines (simple resample, phase-vocoder stretch, zero-crossing realignment) with precise ratio bookkeeping. |
| retro_tape_tools.analysis.time_domain | Pulse detection, edge timing histograms, running energy metrics. |
| retro_tape_tools.analysis.spectral | FFT summaries, spectrogram generation, cepstrum for periodicity hints. |
| retro_tape_tools.analysis.bitgrid | Convert pulses to candidate bit timings, infer baud rates, emit CSV/JSON heuristics. |
| retro_tape_tools.cli | Typer CLI; orchestrates pipeline, parameter validation, and progress reporting via Rich. |
| retro_tape_tools.reporting | Consolidates artifacts into a human-friendly report folder. |

## CLI Surface (Typer)

1. retro-tape analyze PATH [--speed 8 --speed 800 ...]
   - Runs full pipeline for one or more target speed ratios.
2. retro-tape inspect PATH
   - Quick metadata dump (channels, sample rate, duration, RMS per channel).
3. retro-tape export PATH --speed 8
   - Produce WAV and CSV/JSON at a specific resample ratio without heavy analysis.

All commands share a --workspace argument that defines where reports land (retro_outputs/<stem>/speed_<ratio>/).

## Data Artifacts

retro_outputs/
   lsig/
        speed_008.000x/
             conditioned.wav
             speed_adjusted.wav
             spectrogram.png
             pulse_histogram.png
             bitgrid.csv
             report.json

Artifacts are tagged with the effective sample rate + ratio used, so downstream tools can rehydrate correct timing.

## Extensibility

- Config models (Pydantic) allow new tape formats or machine profiles (e.g., C64, ZX Spectrum) to define expected baud/tones.
- Additional detectors (e.g., Manchester decoding) can plug into analysis.bitgrid without altering core CLI.