Upload README.md with huggingface_hub

README.md

@@ -27,60 +27,87 @@ library_name: transformers
 
 # Tiny Audio
 
-An English speech recognition model that outputs punctuated, capitalized, formatted text. Built with
-[Tiny Audio](https://github.com/alexkroman/tiny-audio)—a minimal, hackable ASR framework.
+**A tiny, hackable, open-source speech LLM.**
 
-A frozen Granite Speech encoder is connected to a frozen Qwen3.5-2B decoder through a trained MLP
-projector, with LoRA adapters on the decoder. Only ~80M parameters are trained.
+It transcribes English with punctuation, capitalization, word timestamps, and speaker labels: 1.8%
+WER on LibriSpeech test-clean and 8.4% averaged over 12 benchmarks. Built and trained with
+[Tiny Audio](https://github.com/alexkroman/tiny-audio).
+
+**[Try the live demo](https://huggingface.co/spaces/mazesmazes/tiny-audio)** ·
+**[Train your own](https://github.com/alexkroman/tiny-audio)** ·
+**[Free 3.5-hour course](https://github.com/alexkroman/tiny-audio/blob/main/docs/course/0-course-overview.md)**
 
 ## Quick Start
 
+```bash
+pip install "transformers>=5.0" peft torch torchaudio librosa
+```
+
 ```python
 from transformers import pipeline
 
 pipe = pipeline(
     "automatic-speech-recognition", model="mazesmazes/tiny-audio", trust_remote_code=True
 )
-result = pipe("audio.wav")
-print(result["text"])
+print(pipe("audio.wav")["text"])
 # The quarterly revenue grew by 12% according to Dr. Smith.
 ```
 
-## Usage Examples
-
-### Basic Transcription
+The input can be a file path, a URL, or a 16 kHz float32 numpy array. No post-processing is needed:
+the model writes punctuation, capitalization, and numbers itself.
 
-```python
-from transformers import pipeline
+## Benchmarks
 
-pipe = pipeline(
-    "automatic-speech-recognition", model="mazesmazes/tiny-audio", trust_remote_code=True
-)
+Word error rate (%, lower is better) on 1,000 samples per dataset, scored with the
+[Tiny Audio eval harness](https://github.com/alexkroman/tiny-audio/tree/main/scripts/eval)
+(`ta eval`) after text normalization.
 
-# From file
-result = pipe("audio.wav")
-print(result["text"])
+| Dataset                |      WER |
+| ---------------------- | -------: |
+| LibriSpeech test-clean |     1.80 |
+| SPGISpeech             |     2.24 |
+| LibriSpeech test-other |     3.09 |
+| TED-LIUM               |     3.74 |
+| LoquaciousSet †        |     6.10 |
+| Common Voice           |     6.62 |
+| VoxPopuli              |     6.96 |
+| AMI (IHM)              |     8.88 |
+| GigaSpeech             |     9.07 |
+| Earnings22 †           |    10.54 |
+| People's Speech        |    17.69 |
+| AMI (SDM)              |    23.59 |
+| **Mean (12 sets)**     | **8.36** |
 
-# From URL
-result = pipe("https://example.com/audio.mp3")
+† Held out: no data from this source was used in training.
 
-# From numpy array (must be 16kHz)
-import numpy as np
+To reproduce a row, or score AssemblyAI, Deepgram, ElevenLabs, or Apple's on-device recognizer on
+the same samples:
 
-audio = np.random.randn(16000).astype(np.float32)  # 1 second
-result = pipe(audio)
+```bash
+git clone https://github.com/alexkroman/tiny-audio.git && cd tiny-audio && poetry install
+poetry run ta eval -m mazesmazes/tiny-audio -d loquacious -n 100
+ASSEMBLYAI_API_KEY=... poetry run ta eval -m assemblyai -d loquacious -n 100
 ```
 
-### Batch Processing
+## More Than Plain Text
+
+### Batches and GPU
 
 ```python
-files = ["audio1.wav", "audio2.wav", "audio3.wav"]
-results = pipe(files, batch_size=4)
-for r in results:
+import torch
+
+pipe = pipeline(
+    "automatic-speech-recognition",
+    model="mazesmazes/tiny-audio",
+    trust_remote_code=True,
+    device="cuda",
+    torch_dtype=torch.bfloat16,
+)
+for r in pipe(["audio1.wav", "audio2.wav", "audio3.wav"], batch_size=4):
     print(r["text"])
 ```
 
-### Word-Level Timestamps
+### Word-level timestamps
 
 `return_timestamps=True` times every word with
 [Qwen3-ForcedAligner-0.6B](https://huggingface.co/Qwen/Qwen3-ForcedAligner-0.6B-hf) and returns them
@@ -96,15 +123,13 @@ for word in result["words"]:
 #   {'word': 'Hi,', 'start': 0.0, 'end': 0.24}
 ```
 
-### Speaker Diarization
+### Speaker diarization
 
-`return_speakers=True` labels every word with a speaker (it implies `return_timestamps=True`).
-Speakers come from [Nemotron-3-Diarization](https://huggingface.co/nvidia/Nemotron-3-Diarization),
-run once over the whole recording, so labels stay consistent across hour-long meetings; it handles
-overlapping speech and up to 8 speakers. Each word goes to the speaker most active while it was
-spoken.
+Pass `return_speakers=True` to label every word with who said it. It also turns on word timestamps.
+It works on recordings of any length, keeps speaker labels consistent across hour-long meetings, and
+handles overlapping speech and up to 8 speakers.
 
-Nemotron-3-Diarization is in transformers `main`, not yet a release:
+Diarization needs transformers installed from `main` until the next release:
 
 ```bash
 pip install git+https://github.com/huggingface/transformers
@@ -136,73 +161,25 @@ go to the closest kept speaker:
 result = pipe("call.wav", return_speakers=True, num_speakers=2)
 ```
 
-If alignment or diarization fails (for example, transformers without Nemotron), the transcript is
-still returned and the error is reported under `result["timestamp_error"]` or
-`result["diarization_error"]`.
+If alignment or diarization fails (for example, on a transformers release without diarization
+support), the transcript is still returned and the error is reported under
+`result["timestamp_error"]` or `result["diarization_error"]`.
 
-### GPU Inference
+## Train Your Own
 
-```python
-import torch
-
-pipe = pipeline(
-    "automatic-speech-recognition",
-    model="mazesmazes/tiny-audio",
-    trust_remote_code=True,
-    device="cuda",
-    torch_dtype=torch.bfloat16,
-)
-```
-
-## Benchmarks
-
-Word error rate (%, lower is better) on 1,000 samples per dataset, scored with the
-[Tiny Audio eval harness](https://github.com/alexkroman/tiny-audio/tree/main/scripts/eval)
-(`ta eval`) after text normalization.
-
-| Dataset                |      WER |
-| ---------------------- | -------: |
-| LibriSpeech test-clean |     1.80 |
-| SPGISpeech             |     2.24 |
-| LibriSpeech test-other |     3.09 |
-| TED-LIUM               |     3.74 |
-| LoquaciousSet †        |     6.10 |
-| Common Voice           |     6.62 |
-| VoxPopuli              |     6.96 |
-| AMI (IHM)              |     8.88 |
-| GigaSpeech             |     9.07 |
-| Earnings22 †           |    10.54 |
-| People's Speech        |    17.69 |
-| AMI (SDM)              |    23.59 |
-| **Mean (12 sets)**     | **8.36** |
-
-† Held out: no data from this source was used in training.
+Everything that produced this model is open: the code, the data mix, and the recipe. Swap the
+encoder, the LLM, or the projector from config and train on your own data. A smoke test runs on a
+laptop in about five minutes:
 
-## Architecture
-
-```text
-Audio (16kHz) → Granite Speech encoder (frozen) → MLP projector (trained)
-  → Qwen3.5-2B + LoRA (trained adapters) → Text
+```bash
+git clone https://github.com/alexkroman/tiny-audio.git && cd tiny-audio && poetry install
+poetry run python scripts/train.py +experiments=mps_smoke
 ```
 
-| Component      | Model                                                                                                   | Parameters | Status  |
-| -------------- | ------------------------------------------------------------------------------------------------------- | ---------- | ------- |
-| Audio Encoder  | [granite-speech-5.0-470m-turboctc](https://huggingface.co/ibm-granite/granite-speech-5.0-470m-turboctc) | ~470M      | Frozen  |
-| Projector      | 2-layer MLP (hidden 4096)                                                                               | 12.6M      | Trained |
-| Language Model | [Qwen3.5-2B](https://huggingface.co/Qwen/Qwen3.5-2B)                                                    | ~2B        | Frozen  |
-| LoRA adapters  | r=64, alpha=64, all linear layers                                                                       | 67.3M      | Trained |
-
-### How It Works
-
-1. **Audio encoder**: Granite Speech turns 16kHz audio into frame-level embeddings.
-1. **Projector**: A 2-layer MLP maps those embeddings into the decoder's embedding space. Each
-   projected frame replaces an `<audio>` placeholder token in the prompt.
-1. **Language model**: Qwen3.5-2B, adapted with LoRA, generates the transcript conditioned on the
-   projected audio and the prompt *"Transcribe the speech with proper punctuation and
-   capitalization"*.
-
-At inference, 0.25s of silence is prepended to each clip (`inference_lead_in_seconds`). This keeps
-the first word from being dropped on clips that start mid-speech.
+The
+[free course](https://github.com/alexkroman/tiny-audio/blob/main/docs/course/0-course-overview.md)
+walks through how the pieces fit, training a model, evaluating it, and publishing it with a demo
+like [this one](https://huggingface.co/spaces/mazesmazes/tiny-audio).
 
 ## Model Specifications
 
@@ -210,7 +187,7 @@ the first word from being dropped on clips that start mid-speech.
 | ---------------- | ------------------------------------------------------------------ |
 | Input            | Audio (16kHz mono)                                                 |
 | Output           | Punctuated, capitalized text with formatted numbers                |
-| Max Audio Length | ~30 seconds per call                                               |
+| Max Audio Length | ~19 s per plain call; any length with timestamps or speakers       |
 | Vocabulary       | Qwen3.5 tokenizer                                                  |
 | Languages        | English only                                                       |
 | Generation       | Greedy decoding (num_beams=1, do_sample=False), max 256 new tokens |
@@ -239,7 +216,7 @@ The training recipe is
   `return_speakers=True`, which transcribe in 8-18 s chunks automatically.
 - **Speaker diarization**: At most 8 speakers per recording. The count is detected automatically;
   `num_speakers` and `max_speakers` can cap it, but `min_speakers` is not supported (passing it
-  raises a `ValueError`). Needs transformers `main` until a release includes Nemotron-3-Diarization.
+  raises a `ValueError`). Needs transformers `main` until the next release.
 - **Accuracy**: May degrade on:
   - Far-field and overlapping speech (see AMI SDM)
   - Noisy or low-quality audio
@@ -284,13 +261,6 @@ If you use this model, please cite:
 }
 ```
 
-## Links
-
-- [GitHub Repository](https://github.com/alexkroman/tiny-audio) - Train your own model
-- [Free 3.5-hour Course](https://github.com/alexkroman/tiny-audio/blob/main/docs/course/0-course-overview.md)
-  \- Learn ASR from scratch
-- [Live Demo](https://huggingface.co/spaces/mazesmazes/tiny-audio) - Try it in your browser
-
 ## Acknowledgments
 
 - [Granite Speech](https://huggingface.co/ibm-granite/granite-speech-5.0-470m-turboctc) for the