init

README.md

@@ -0,0 +1,157 @@
+tcdweb — Transcode Detector (Web Version)
+=========================================
+
+**tcdweb** is a browser-based audio authenticity analyzer that determines whether
+an audio file is a genuine native encode or a *transcode* (lossy → lossless
+re-encode). It can also detect *upscaling* (a lossy file re-encoded at a higher
+bitrate by the same lossy codec, e.g. 128 → 320 kbps MP3).
+
+This is the **web version** of [tcd](https://codeberg.org/armin/tcd), the
+original CLI tool. At this point **tcdweb is a complete, independent fork** with
+its own codebase, its own analysis engine, and its own UI. It runs entirely in
+the browser via the **Web Audio API** — no server-side processing, no file
+uploads, no FFmpeg dependency, and no command line needed.
+
+---
+
+Obligatory AI-slop disclaimer
+-----------------------------
+
+tcdweb is 98% vibe-coded (a.k.a. "ai slop"). If that's a problem for you, please
+kindly just use a different tool. There is also absolutely *NO* guarantee this
+will work reliably, be useful in any way, or even make any sense whatsoever.
+
+---
+
+What it does
+------------
+
+Drag or load an audio file, and tcdweb will:
+
+1. Decode it client-side using the browser's built-in decoder
+2. Compute the frequency spectrum via a Hann-windowed FFT (4096-point, 50% overlap)
+3. Extract five key metrics (see below)
+4. Apply a two-layer verdict system to classify the file
+5. Display a detailed decision log, confidence score, and interactive charts
+
+It includes a **realtime FFT analyzer**, a **waveform viewer with playback**,
+**BPM detection**, **metadata tag parsing** (ID3v1/v2, FLAC, APE), and a full
+data table with every computed value.
+
+---
+
+Key metrics
+-----------
+
+- **Cutoff**: highest frequency with measurable energy (as Hz and % of Nyquist).
+  Lossy codecs chop off high frequencies — the lower the cutoff, the more
+  aggressive the compression.
+- **Steepness (Transition Bandwidth)**: how abruptly the spectrum drops at the
+  cutoff point. Lossy encoders produce sharp brick-wall filters (low steepness).
+- **Noise Floor**: average noise level in the top quartile of the spectrum.
+  Lossy quantization raises the noise floor.
+- **Roughness (Coefficient of Variation)**: how jagged/bumpy the spectrum is
+  before the cutoff. Lossy encoding introduces quantization noise that creates
+  spectral scalloping.
+- **Band Ratio**: energy ratio between 16–20 kHz and 12–16 kHz. Transcodes show
+  an unnatural dip in the top octave.
+
+---
+
+Supported formats
+-----------------
+
+| Lossy | Lossless |
+|---|---|
+| MP3 | FLAC |
+| AAC / M4A | WAV / AIFF |
+| Ogg Vorbis | ALAC |
+| Opus | WavPack (WV) |
+| WMA | APE |
+| AC3 / EAC3 | DSF / DFF |
+| MP2 / MP1 | |
+
+Support depends on the browser's built-in decoder (all modern browsers support
+the most common formats).
+
+---
+
+Verdicts
+--------
+
+| Verdict | Input codec | Meaning |
+|---|---|---|
+| **NATIVE** | lossy | Single encode at the stated bitrate — genuine |
+| **UPSCALED** | lossy | Re-encoded from a lower bitrate (e.g. 128 → 320 kbps) |
+| **GENUINE** | lossless | No evidence of lossy origin |
+| **TRANSCODE** | lossless | Originated from a lossy source, decoded to lossless |
+| **SILENT** | any | No detectable audio content |
+
+---
+
+Detection logic
+---------------
+
+The verdict is determined in two layers:
+
+**Layer 1 (Primary)** — Cutoff + Steepness. A low cutoff combined with a sharp
+drop (low steepness) is a definitive sign of a lossy encoder's lowpass filter.
+
+**Layer 2 (Secondary)** — Roughness + Band Ratio. Applied when the cutoff is
+high enough to pass Layer 1. Catches transcodes where the cutoff is near
+Nyquist but the spectrum still shows quantization artifacts.
+
+Lossy files are checked for upscaling by comparing the cutoff ratio to
+bitrate-specific expectations.
+
+---
+
+Confidence score (0–100%)
+-------------------------
+
+A continuous score based on how far the metrics deviate from the thresholds.
+Higher confidence means stronger evidence supporting the verdict.
+
+---
+
+How it differs from the original tcd CLI
+-----------------------------------------
+
+| Feature | tcd (CLI) | tcdweb |
+|---|---|---|
+| Platform | C program, command line | Pure JavaScript, browser |
+| Decoder | FFmpeg (system dep) | Web Audio API (built-in) |
+| Analysis | 4096 FFT, same algorithm | 4096 FFT, same algorithm |
+| Realtime spectrum | Terminal TUI | Canvas-based interactive chart |
+| Playback | No | Yes, with waveform and seek |
+| BPM detection | No | Yes (autocorrelation) |
+| Metadata parsing | No | ID3v1/v2, FLAC, APE |
+| Stereo mode / VBR info | No | Yes (MP3 header parsing) |
+| File size limit | None | Browser memory (~2 GB typical) |
+
+---
+
+Limitations
+-----------
+
+- **Browser audio decoding** limits which formats work (depends on `AudioContext.decodeAudioData`).
+- **Very short files** (< 4096 samples) cannot be analyzed.
+- **High-bitrate lossy encodes** (320 kbps MP3, 256 kbps AAC) may not be
+  distinguishable from lossless by cutoff alone.
+- **Already-filtered material** (e.g. deliberate 15 kHz LPF during mastering)
+  may produce false positives.
+
+---
+
+References
+----------
+
+- Nyquist–Shannon sampling theorem — Wikipedia
+  https://en.wikipedia.org/wiki/Nyquist–Shannon_sampling_theorem
+- Equal-loudness contour (Fletcher–Munson curves) — Wikipedia
+  https://en.wikipedia.org/wiki/Equal-loudness_contour
+- LAME MP3 encoder psychoacoustic model — Hydrogenaudio Knowledge Base
+  https://wiki.hydrogenaudio.org/index.php?title=LAME
+- "Audio Authentication Using Spectral Analysis" — University of Michigan
+  open-access thesis, 2025
+  https://doi.org/10.7302/28306