{
  "id": "voice-note-transcriber-pipeline",
  "title": "Voice Note Transcriber Pipeline",
  "level": 3,
  "levelName": "Engineer",
  "tagline": "Turn a selected WAV into an inspectable transcript and caption review page using a real optional HTTP recognizer, with an honest offline speech fixture.",
  "summary": "Turn a selected WAV into an inspectable transcript and caption review page using a real optional HTTP recognizer, with an honest offline speech fixture.",
  "hours": 8,
  "languages": [
    "Python"
  ],
  "status": "ready",
  "source": "core",
  "author": {
    "name": "AI Engineering from Scratch",
    "github": "rohitg00"
  },
  "youWillBuild": "audio.wav, captions.vtt, transcript.json and an HTML page with embedded playback and cue-seek buttons.",
  "usefulFor": [
    "audio.wav, captions.vtt, transcript.json and an HTML page with embedded playback and cue-seek buttons."
  ],
  "skills": [
    "Decode the audio clock before processing",
    "Measure activity without claiming speech detection",
    "Send real WAV bytes through a recognizer boundary",
    "Export a transcript you can hear and correct"
  ],
  "prerequisites": [
    "Python bytes, lists and context managers.",
    "Sample rate, channels and signed integer audio samples.",
    "A callable provider interface and basic HTTP request structure."
  ],
  "figures": true,
  "overviewFigure": "pj-voice-note-transcriber-pipeline-1",
  "languageWhy": {
    "Python": "Stdlib data structures, explicit algorithms and deterministic local tests."
  },
  "demo": {
    "command": [
      "python3",
      "demo.py"
    ],
    "cwd": "solution"
  },
  "stages": [
    {
      "id": "01-pcm",
      "title": "Decode the audio clock before processing",
      "summary": "The integer samples 0, 16384 and -16384 become 0, 0.5 and -0.5. A sample index of 800 at 16000 Hz means 0.05 seconds. Interpreting the same index at 8000 Hz would double the timestamp without changing a single byte.",
      "language": "python",
      "languageWhy": "Python standard-library collections, bytes and file operations expose this stage directly.",
      "hours": 2,
      "difficulty": "starter",
      "figure": "pj-voice-note-transcriber-pipeline-1",
      "concepts": [
        "PCM WAV",
        "sample normalization",
        "sample clock"
      ]
    },
    {
      "id": "02-activity",
      "title": "Measure activity without claiming speech detection",
      "summary": "At 1000 Hz, forty samples of amplitude0.5, twenty silent samples and forty active samples merge into [0,100] when gap_ms is40. The merged span lasts100 ms. A20 ms isolated burst is discarded when min_ms is40.",
      "language": "python",
      "languageWhy": "Python standard-library collections, bytes and file operations expose this stage directly.",
      "hours": 2,
      "difficulty": "core",
      "figure": "pj-voice-note-transcriber-pipeline-2",
      "concepts": [
        "RMS energy",
        "gap merging",
        "activity limits"
      ]
    },
    {
      "id": "03-transcribe",
      "title": "Send real WAV bytes through a recognizer boundary",
      "summary": "A provider timeout followed by success records attempts=2. Each output row retains start, end, text and the SHA256 of the exact encoded segment. A second segment cannot overlap the previous one, and fractional sample indices are invalid.",
      "language": "python",
      "languageWhy": "Python standard-library collections, bytes and file operations expose this stage directly.",
      "hours": 2,
      "difficulty": "core",
      "figure": "pj-voice-note-transcriber-pipeline-3",
      "concepts": [
        "multipart HTTP",
        "bounded retry",
        "audio hashes"
      ]
    },
    {
      "id": "04-captions",
      "title": "Export a transcript you can hear and correct",
      "summary": "The fixture CLI pairs the original spoken clip with its supplied reference text and labels the method clearly. Real recognition instead uses --endpoint. After inspecting playback, edit the rows in transcript.json and run --review-file to rerender; the report must match the original audio hash.",
      "language": "python",
      "languageWhy": "Python standard-library collections, bytes and file operations expose this stage directly.",
      "hours": 2,
      "difficulty": "stretch",
      "figure": "pj-voice-note-transcriber-pipeline-4",
      "concepts": [
        "WebVTT",
        "audio review",
        "portable exports"
      ]
    }
  ],
  "demos": [
    {
      "gif": "media/run.gif",
      "poster": "media/run.png",
      "title": "Initialize and grade",
      "caption": "Recorded starter failure followed by all reference-solution stages passing. Reference passes do not earn learner certificates."
    },
    {
      "gif": "media/output.gif",
      "poster": "media/output.png",
      "title": "Inspect the output",
      "caption": "Actual output from the local deterministic demo command. See the README for fixture and live-adapter limits."
    }
  ]
}