Update README.md

README.md

@@ -7,63 +7,35 @@ tags:
   - dit
   - audio
   - educational
-  - from-scratch
+  - research
 pipeline_tag: text-to-audio
 ---
 
 # QaDiT — text-to-audio latent Diffusion Transformer
 
-> **Educational / research build.** This is not a state-of-the-art text-to-audio
-> system. It is a from-scratch DiT trained on a budget so you can see how latent
-> audio diffusion is wired, how the loss behaves, and what a mid-scale run
-> actually produces. The model already learns useful representations and can
-> generate solid samples for many prompts — but peak quality will need longer
-> training and broader data. That next stage is planned.
+> **Research / educational artifact.** This is **not** a state-of-the-art
+> text-to-audio host model. It is a from-scratch DiT trained on a modest budget
+> so the full stack is readable, reproducible, and improvable. Quality already
+> shows that the pipeline works; pushing further is mostly **more data and
+> longer training**, not a different architecture.
 
-Part of **[QuarkML](PLACEHOLDER_WEBSITE)** — public lab notes by
-**[Sidharth GN](PLACEHOLDER_AUTHOR_PAGE)**: pick an architecture, implement it
-from nothing, train it on hardware a normal person can afford, then publish the
-code, weights, numbers, and what broke along the way.
+A ~159M-parameter latent Diffusion Transformer that turns a text caption into
+**10.24 s of 16 kHz mono audio**: FLAN-T5 conditioning → DiT denoising of
+AudioLDM KL-VAE latents → VAE decode → HiFi-GAN vocoder.
 
-| | |
-| --- | --- |
-| **Website write-up** | [PLACEHOLDER_WEBSITE_POST](PLACEHOLDER_WEBSITE_POST) |
-| **Training / sampling code** | [PLACEHOLDER_GITHUB_REPO](PLACEHOLDER_GITHUB_REPO) |
-| **This weights repo** | [PLACEHOLDER_HF_MODEL](PLACEHOLDER_HF_MODEL) |
-| **Author** | [Sidharth GN](PLACEHOLDER_AUTHOR_PAGE) · [QuarkML](PLACEHOLDER_WEBSITE) |
-| **Contact / social** | [PLACEHOLDER_TWITTER](PLACEHOLDER_TWITTER) · [PLACEHOLDER_LINKEDIN](PLACEHOLDER_LINKEDIN) · [PLACEHOLDER_EMAIL](mailto:PLACEHOLDER_EMAIL) |
+Weights are the **EMA** copy from training step **23,999**.
 
 ---
 
-## What this model is (and is not)
-
-**Is:** a ~159M-parameter latent Diffusion Transformer (DiT-B) that turns a text
-caption into **10.24 s of 16 kHz mono audio**. Built to teach the full stack —
-mel VAE latents, T5 conditioning, v-prediction training, DDIM + CFG sampling,
-REPA alignment — with runnable code and publishable weights.
+## Architecture at a glance
 
-**Is not:** a production AudioLDM / Tango / Stable Audio competitor. Prompt
-adherence and timbre fidelity are good enough to demonstrate that the pipeline
-works and that the representation is learning, not good enough to claim SOTA.
-Improving that means **more steps, more diverse data, and the usual scaling
-knobs** — not a different architecture fantasy.
-
-If you came here to learn how modern latent audio diffusion is trained on a
-budget, you are in the right place. If you need broadcast-quality SFX on every
-prompt, wait for a longer run or use a larger released system.
-
----
-
-## Architecture
-
-<!-- Replace the placeholder image with your diagram (e.g. assets/architecture.png). -->
+Drop a rendered overview PNG at [`assets/architecture.png`](assets/architecture.png)
+if you want a Hub thumbnail; the Mermaid diagrams below are the source of truth
+and render on GitHub / the Hub.
 
 ![Architecture diagram](assets/architecture.png)
 
-*Placeholder — drop the DiT + T5 + VAE + vocoder diagram at
-`assets/architecture.png` (or update the path above).*
-
-**Pipeline at a glance**
+*Optional image — place your export at `assets/architecture.png`.*
 
 ```text
 caption
@@ -77,57 +49,294 @@ caption
 | Piece | Choice |
 | --- | --- |
 | Backbone | DiT-B — depth 12, width 768, 12 heads, MLP ratio 4.0 (~159M) |
-| Latent grid | `[8, 256, 16]` AudioLDM KL-VAE latents |
+| Latent grid | `[8, 256, 16]` (channels × time × freq) |
 | Patchify | 2×2 → **1024** tokens, fixed 2-D sincos positions |
 | Text | FLAN-T5-large cross-attention every block + pooled text in adaLN-Zero |
-| Train target | **v-prediction** (Salimans & Ho) |
+| Train target | **v-prediction** |
 | Noise schedule | **cosine** ᾱ, T = 1000 |
-| Timestep sampling (train) | logit-normal (SD3-style) |
-| CFG | p_uncond = 0.1 train; default guidance scale **4.0** at sample |
-| Sampler | **DDIM**, default **50** steps, η = 0 (deterministic) |
-| Aux loss | REPA vs frozen AST features (train-time only; dropped at inference) |
-| Decode stack | `cvssp/audioldm-s-full-v2` VAE + HiFi-GAN vocoder |
+| Timestep sampling (train) | logit-normal |
+| CFG | p_uncond = 0.1 train; default guidance **4.0** at sample |
+| Sampler | **DDIM**, default **50** steps, η = 0 |
+| Aux loss | REPA vs frozen AST features (train only) |
+| Decode stack | `cvssp/audioldm-s-full-v2` VAE + HiFi-GAN |
 
-Weights in this repo are the **EMA** copy from training step **23999**.
+> **Color legend for diagrams:** 🟦 blue = frozen pretrained · 🟩 green = trainable
+> (DiT + glue) · 🟨 yellow = data / tensors · 🟥 red = losses
 
 ---
 
-## Training objective and sampling (DDIM + v-prediction)
+## 1. Big picture — three pipelines
 
-Training and sampling are deliberately a small, classic stack — easy to read
-in the code, not a research sampler zoo.
+```mermaid
+flowchart LR
+    A[/"AudioCaps<br/>~46K clips + captions"/] --> B["① Offline Pre-compute<br/>(run frozen models once,<br/>cache to disk)"]
+    B --> C["② Training Loop<br/>(only the DiT trains)"]
+    C --> D["③ Inference / Sampling<br/>(caption → waveform)"]
 
-**Forward process**
+    style A fill:#fff3c4,stroke:#b8860b,color:#000
+    style B fill:#dbeafe,stroke:#1e40af,color:#000
+    style C fill:#dcfce7,stroke:#15803d,color:#000
+    style D fill:#fde2e2,stroke:#b91c1c,color:#000
+```
 
-\[
-z_t = \sqrt{\bar\alpha_t}\, z_0 + \sqrt{1-\bar\alpha_t}\,\varepsilon
-\]
+---
 
-**Network target (v-prediction)**
+## 2. Offline pre-compute (frozen models, run once)
+
+Heavy frozen models run **once**; the training loop never loads T5, the VAE,
+or the REPA encoder.
+
+```mermaid
+flowchart TD
+    subgraph INPUT["Per clip"]
+        WAV[/"waveform<br/>10.24 s · 16 kHz · mono"/]
+        CAP[/"caption (text)"/]
+    end
+
+    subgraph FRONT["Mel front-end (locked to VAE)"]
+        MEL["STFT → log-mel<br/>n_fft 1024 · hop 160 · 64 mels<br/>→ mel 1×1024×64"]
+    end
+
+    subgraph FROZEN["Frozen pretrained encoders 🟦"]
+        VAE["AudioLDM mel-VAE<br/>encoder (÷4, C=8)"]
+        T5["FLAN-T5 encoder"]
+        AST["AST<br/>(REPA target encoder)"]
+    end
+
+    subgraph CACHE["Cached to sharded records 🟨"]
+        Z0[/"z₀ latent · 8×256×16<br/>(scaled by latent_scale → unit std)"/]
+        CTX[/"text states c ∈ ℝ^{64×1024}<br/>+ attention mask"/]
+        YSTAR[/"REPA target features y*"/]
+    end
+
+    WAV --> MEL
+    MEL --> VAE --> Z0
+    CAP --> T5 --> CTX
+    MEL --> AST --> YSTAR
+
+    style WAV fill:#fff3c4,stroke:#b8860b,color:#000
+    style CAP fill:#fff3c4,stroke:#b8860b,color:#000
+    style MEL fill:#e0e7ff,stroke:#4338ca,color:#000
+    style VAE fill:#dbeafe,stroke:#1e40af,color:#000
+    style T5 fill:#dbeafe,stroke:#1e40af,color:#000
+    style AST fill:#dbeafe,stroke:#1e40af,color:#000
+    style Z0 fill:#fff3c4,stroke:#b8860b,color:#000
+    style CTX fill:#fff3c4,stroke:#b8860b,color:#000
+    style YSTAR fill:#fff3c4,stroke:#b8860b,color:#000
+```
 
-\[
-v = \sqrt{\bar\alpha_t}\,\varepsilon - \sqrt{1-\bar\alpha_t}\, z_0
-\]
+---
+
+## 3. Training step (what is actually optimized)
+
+Only the **DiT** and its small glue layers receive gradients.
+
+```mermaid
+flowchart TD
+    subgraph BATCH["Batch from cache 🟨"]
+        Z0[/"z₀' scaled latent"/]
+        C[/"T5 tokens c + mask"/]
+        YS[/"REPA target y*"/]
+    end
+
+    subgraph NOISE["Forward diffusion"]
+        TS["sample t ~ logit-normal"]
+        EPS["sample ε ~ N(0, I)"]
+        ZT["z_t = √ᾱ_t · z₀' + √(1−ᾱ_t) · ε"]
+    end
+
+    CFGDROP{"CFG dropout<br/>p = 0.1?"}
+    NULL["learned null ∅ 🟩"]
+
+    subgraph DIT["DiT — the ONLY trained network 🟩"]
+        PATCH["patchify 2×2 + 2-D pos-emb<br/>→ 1024 tokens"]
+        BLOCKS["12 × DiT blocks<br/>(self-attn → cross-attn → MLP,<br/>adaLN-Zero from t + pooled text)"]
+        HL["hidden state h_ℓ<br/>(block ℓ = 4)"]
+        HEAD["unpatchify head"]
+    end
+
+    PROJ["MLP projection g(·) 🟩"]
+    PRED[/"prediction v̂"/]
+
+    LDIFF{{"L_diff = ‖v − v̂‖²"}}
+    LREPA{{"L_REPA = −cos(g(h_ℓ), y*)"}}
+    LTOT{{"L = L_diff + λ·L_REPA<br/>(λ = 0.5, decayed)"}}
+
+    OPT["AdamW + EMA(0.9999)<br/>→ DiT weights only"]
+
+    Z0 --> ZT
+    TS --> ZT
+    EPS --> ZT
+    ZT --> PATCH
+    C --> CFGDROP
+    CFGDROP -- "90% keep" --> BLOCKS
+    CFGDROP -- "10% drop" --> NULL --> BLOCKS
+    TS -- "adaLN-Zero" --> BLOCKS
+    PATCH --> BLOCKS --> HEAD --> PRED
+    BLOCKS -.-> HL --> PROJ
+    PROJ --> LREPA
+    YS --> LREPA
+    PRED --> LDIFF
+    LDIFF --> LTOT
+    LREPA --> LTOT
+    LTOT --> OPT
+
+    style Z0 fill:#fff3c4,stroke:#b8860b,color:#000
+    style C fill:#fff3c4,stroke:#b8860b,color:#000
+    style YS fill:#fff3c4,stroke:#b8860b,color:#000
+    style TS fill:#e0e7ff,stroke:#4338ca,color:#000
+    style EPS fill:#e0e7ff,stroke:#4338ca,color:#000
+    style ZT fill:#e0e7ff,stroke:#4338ca,color:#000
+    style CFGDROP fill:#fef9c3,stroke:#a16207,color:#000
+    style NULL fill:#dcfce7,stroke:#15803d,color:#000
+    style PATCH fill:#dcfce7,stroke:#15803d,color:#000
+    style BLOCKS fill:#dcfce7,stroke:#15803d,color:#000
+    style HL fill:#dcfce7,stroke:#15803d,color:#000
+    style HEAD fill:#dcfce7,stroke:#15803d,color:#000
+    style PROJ fill:#dcfce7,stroke:#15803d,color:#000
+    style PRED fill:#fff3c4,stroke:#b8860b,color:#000
+    style LDIFF fill:#fde2e2,stroke:#b91c1c,color:#000
+    style LREPA fill:#fde2e2,stroke:#b91c1c,color:#000
+    style LTOT fill:#fde2e2,stroke:#b91c1c,color:#000
+    style OPT fill:#dcfce7,stroke:#15803d,color:#000
+```
+
+---
+
+## 4. Inside one DiT block
+
+```mermaid
+flowchart TD
+    TOKENS[/"latent tokens (queries)"/] --> LN1["LayerNorm ⊕ adaLN-Zero<br/>(scale, shift, gate from t-emb)"]
+    LN1 --> SA["Self-Attention<br/>(latent ↔ latent)"]
+    SA --> ADD1(("＋"))
+    TOKENS --> ADD1
+
+    ADD1 --> LN2["LayerNorm"]
+    LN2 --> CA["Cross-Attention<br/>Q = latent tokens<br/>K,V = T5 text tokens c<br/>(+ padding mask)"]
+    TXT[/"T5 tokens c 🟨"/] --> CA
+    CA --> ADD2(("＋"))
+    ADD1 --> ADD2
+
+    ADD2 --> LN3["LayerNorm ⊕ adaLN-Zero"]
+    LN3 --> MLP["Feed-Forward MLP"]
+    MLP --> ADD3(("＋"))
+    ADD2 --> ADD3
+    ADD3 --> OUT[/"tokens → next block"/]
+
+    TEMB[/"t-embedding<br/>(sinusoidal → MLP,<br/>+ pooled text vector)"/] -. "scale · shift · gate" .-> LN1
+    TEMB -. "scale · shift · gate" .-> LN3
+
+    style TOKENS fill:#fff3c4,stroke:#b8860b,color:#000
+    style TXT fill:#fff3c4,stroke:#b8860b,color:#000
+    style TEMB fill:#fff3c4,stroke:#b8860b,color:#000
+    style OUT fill:#fff3c4,stroke:#b8860b,color:#000
+    style LN1 fill:#dcfce7,stroke:#15803d,color:#000
+    style SA fill:#dcfce7,stroke:#15803d,color:#000
+    style LN2 fill:#dcfce7,stroke:#15803d,color:#000
+    style CA fill:#dcfce7,stroke:#15803d,color:#000
+    style LN3 fill:#dcfce7,stroke:#15803d,color:#000
+    style MLP fill:#dcfce7,stroke:#15803d,color:#000
+```
+
+---
+
+## 5. Inference / sampling (caption → waveform)
+
+```mermaid
+flowchart TD
+    CAP[/"caption"/] --> T5["FLAN-T5 encoder 🟦"]
+    T5 --> C[/"text tokens c"/]
+    NULLC[/"null embedding ∅"/]
+
+    ZT[/"z_T ~ N(0, I)<br/>8×256×16"/] --> LOOP
+
+    subgraph LOOP["Reverse sampler · 50 DDIM steps (default)"]
+        DIT["EMA DiT 🟩<br/>two passes: pred(c), pred(∅)"]
+        CFG["CFG combine:<br/>v = v(∅) + w · (v(c) − v(∅))<br/>w = 4.0"]
+        STEP["DDIM update z_t → z_{t−1}"]
+        DIT --> CFG --> STEP
+        STEP -- "next t" --> DIT
+    end
+
+    C --> DIT
+    NULLC --> DIT
+
+    LOOP --> ZH[/"ẑ₀' → un-scale (÷ latent_scale)"/]
+    ZH --> DEC["VAE decoder 🟦"]
+    DEC --> MELO[/"mel-spectrogram"/]
+    MELO --> VOC["HiFi-GAN vocoder 🟦"]
+    VOC --> OUT[/"waveform 🔊<br/>10.24 s · 16 kHz"/]
+
+    style CAP fill:#fff3c4,stroke:#b8860b,color:#000
+    style C fill:#fff3c4,stroke:#b8860b,color:#000
+    style NULLC fill:#fff3c4,stroke:#b8860b,color:#000
+    style ZT fill:#fff3c4,stroke:#b8860b,color:#000
+    style T5 fill:#dbeafe,stroke:#1e40af,color:#000
+    style DIT fill:#dcfce7,stroke:#15803d,color:#000
+    style CFG fill:#e0e7ff,stroke:#4338ca,color:#000
+    style STEP fill:#e0e7ff,stroke:#4338ca,color:#000
+    style ZH fill:#fff3c4,stroke:#b8860b,color:#000
+    style DEC fill:#dbeafe,stroke:#1e40af,color:#000
+    style MELO fill:#fff3c4,stroke:#b8860b,color:#000
+    style VOC fill:#dbeafe,stroke:#1e40af,color:#000
+    style OUT fill:#fff3c4,stroke:#b8860b,color:#000
+```
+
+---
+
+## 6. Component ownership
+
+```mermaid
+flowchart LR
+    subgraph FROZEN["🟦 Frozen (reused pretrained)"]
+        direction TB
+        F1["AudioLDM mel-VAE<br/>(encode + decode)"]
+        F2["FLAN-T5 text encoder"]
+        F3["AST<br/>(REPA target)"]
+        F4["HiFi-GAN vocoder"]
+    end
+
+    subgraph TRAINED["🟩 Trained on AudioCaps"]
+        direction TB
+        T1["DiT-B/2 (~159M)"]
+        T2["T5 → d_model projection"]
+        T3["REPA projection head g(·)<br/>(dropped at inference)"]
+        T4["learned null embedding ∅"]
+    end
+
+    FROZEN -- "latent space, text<br/>features, alignment<br/>targets, waveform decode" --> TRAINED
+
+    style F1 fill:#dbeafe,stroke:#1e40af,color:#000
+    style F2 fill:#dbeafe,stroke:#1e40af,color:#000
+    style F3 fill:#dbeafe,stroke:#1e40af,color:#000
+    style F4 fill:#dbeafe,stroke:#1e40af,color:#000
+    style T1 fill:#dcfce7,stroke:#15803d,color:#000
+    style T2 fill:#dcfce7,stroke:#15803d,color:#000
+    style T3 fill:#dcfce7,stroke:#15803d,color:#000
+    style T4 fill:#dcfce7,stroke:#15803d,color:#000
+```
+
+---
 
-The DiT predicts \(v\); at sample time we recover
+## Training objective (DDIM + v-prediction)
+
+**Forward process**
 
 \[
-\hat z_0 = \sqrt{\bar\alpha_t}\, z_t - \sqrt{1-\bar\alpha_t}\, v,\quad
-\hat\varepsilon = \sqrt{1-\bar\alpha_t}\, z_t + \sqrt{\bar\alpha_t}\, v
+z_t = \sqrt{\bar\alpha_t}\, z_0 + \sqrt{1-\bar\alpha_t}\,\varepsilon
 \]
 
-and step with **DDIM** (η = 0 by default). Classifier-free guidance is applied
-in v-space:
+**Network target**
 
 \[
-v = v_{\text{uncond}} + s\,(v_{\text{cond}} - v_{\text{uncond}})
+v = \sqrt{\bar\alpha_t}\,\varepsilon - \sqrt{1-\bar\alpha_t}\, z_0
 \]
 
-with \(s = 4.0\) unless you override `guidance_scale`. After DDIM, latents are
-divided by `latent_scale` ≈ **0.95035** (unit-variance scaling from the
-precompute cache) before VAE decode.
-
-That whole chain — including CFG against a learned null text token — is what
+At sample time the DiT predicts \(v\); we recover \(\hat z_0\) and
+\(\hat\varepsilon\), then step with **DDIM** (η = 0). CFG is applied in
+v-space with default scale \(s = 4.0\). After DDIM, latents are divided by
+`latent_scale` ��� **0.95035** before VAE decode — that whole chain is what
 `model.generate(...)` runs.
 
 ---
@@ -137,20 +346,13 @@ That whole chain — including CFG against a learned null text token — is what
 | | |
 | --- | --- |
 | Source | [OpenSound/AudioCaps](https://huggingface.co/datasets/OpenSound/AudioCaps) |
-| Split used | `train` |
-| Clips after precompute | **45,178** |
-| Clip length | 10.24 s @ 16 kHz (locked to AudioLDM mel / VAE / vocoder) |
-| Precomputed fields | VAE latents, FLAN-T5 embeddings + mask, AST REPA targets |
-| `latent_scale` | 0.9503493000009796 (stored in this `config.json`) |
+| Split | `train` · **45,178** clips after precompute |
+| Clip length | 10.24 s @ 16 kHz |
+| Cached fields | VAE latents, FLAN-T5 embeddings + mask, AST REPA targets |
+| `latent_scale` | `0.9503493000009796` (baked into `config.json`) |
 
-AudioCaps is captioned environmental / everyday sound — dogs, rain, engines,
-ambience — not a speech or music corpus. Domain limits show up in samples:
-speech and music prompts are out of distribution.
-
-**Next data (planned):** larger / more diverse captioned audio (and longer
-training) to push quality past “good lab demo” toward something closer to
-public SOTA systems. Links and recipes will land on the website write-up when
-that run ships.
+AudioCaps is captioned environmental / everyday sound — not speech or music.
+Those domains are out of distribution for this checkpoint.
 
 ---
 
@@ -159,78 +361,37 @@ that run ships.
 | | |
 | --- | --- |
 | Optimizer | AdamW, lr 1e-4, weight decay 0 |
-| Steps | **23,999** (EMA weights exported) |
+| Steps | **23,999** (EMA exported) |
 | Global batch | 256 (2 GPUs × microbatch 16 × grad accum 8) |
 | EMA decay | 0.9999 |
 | REPA | weight 0.5, decayed over 15k steps |
 | AMP | yes |
-| Seed | 0 |
-
-| Metric | Value |
-| --- | --- |
-| GPU hours | *PLACEHOLDER_GPU_HOURS* |
-| Hardware | *PLACEHOLDER_HARDWARE* (e.g. 2× T4 / 2× A10 / …) |
-| Approx. cost | *PLACEHOLDER_COST* |
-| W&B / logs | *PLACEHOLDER_WANDB_RUN* |
-
-Fill the placeholders above (and the loss figures below) before or right after
-publishing so the Hub page matches the website lab note.
 
 ---
 
 ## Training curves
 
-<!-- Drop PNGs under assets/ and keep these filenames, or edit the paths. -->
+Put W&B / TensorBoard screenshots (or exports) under [`assets/`](assets/) using
+the filenames below. Until then the images show as broken links on the Hub —
+that is intentional so the slots are obvious.
 
 ### Diffusion / total loss
 
 ![Training loss](assets/loss_curve.png)
 
-*Placeholder — `assets/loss_curve.png`*
+*Drop your curve at `assets/loss_curve.png`.*
 
-### REPA loss (train-time alignment)
+### REPA loss
 
 ![REPA loss](assets/repa_loss_curve.png)
 
-*Placeholder — `assets/repa_loss_curve.png`*
+*Drop your curve at `assets/repa_loss_curve.png`.*
 
-### Learning rate / EMA / extras (optional)
+### Learning rate (optional)
 
 ![LR schedule](assets/lr_schedule.png)
 
-*Placeholder — `assets/lr_schedule.png`*
-
----
-
-## Sample outputs
-
-<!-- Optional: host short WAVs on the Hub or link to the website gallery. -->
-
-| Prompt | Audio |
-| --- | --- |
-| *PLACEHOLDER_PROMPT_1* | *[listen](PLACEHOLDER_SAMPLE_1_URL)* |
-| *PLACEHOLDER_PROMPT_2* | *[listen](PLACEHOLDER_SAMPLE_2_URL)* |
-| *PLACEHOLDER_PROMPT_3* | *[listen](PLACEHOLDER_SAMPLE_3_URL)* |
-
-Full gallery and failure cases: [PLACEHOLDER_WEBSITE_POST](PLACEHOLDER_WEBSITE_POST).
-
----
-
-## Results in plain language
-
-- The run **did** learn a working text→latent→mel→wave path. With the default
-  50 DDIM steps and CFG 4.0 you get recognizable ambient / SFX-style audio for
-  many AudioCaps-like prompts.
-- Representation learning looks healthy for the compute spent (REPA +
-  v-prediction DiT on ~45k clips, ~24k steps).
-- It is **not** peak quality: complex scenes, speech, music, and fine timing
-  still fall short of large industrial models.
-- The honest upgrade path is boring and correct: **train longer, add more
-  (and cleaner) data**, retune CFG / steps, keep measuring. Architecture
-  churn is not the bottleneck for this checkpoint.
-
-Write-ups of collapses, flat loss regions, and compute bugs belong on the
-website — those notes are part of the point of QuarkML.
+*Optional: `assets/lr_schedule.png`.*
 
 ---
 
@@ -245,10 +406,7 @@ import soundfile as sf
 import torch
 from transformers import AutoModel
 
-model = AutoModel.from_pretrained(
-    "PLACEHOLDER_HF_MODEL",   # e.g. QuarkML/QaDiT
-    trust_remote_code=True,
-)
+model = AutoModel.from_pretrained("QuarkML/QaDiT", trust_remote_code=True)
 model = model.to("cuda" if torch.cuda.is_available() else "cpu").eval()
 
 out = model.generate(
@@ -260,7 +418,7 @@ out = model.generate(
 sf.write("dog_birds.wav", out.audios[0], out.sampling_rate)
 ```
 
-First `generate` download pulls the frozen helpers this run was trained with:
+First `generate` downloads the frozen helpers this run was trained with:
 `google/flan-t5-large` and the VAE + vocoder from `cvssp/audioldm-s-full-v2`.
 
 ### Output types
@@ -269,7 +427,7 @@ First `generate` download pulls the frozen helpers this run was trained with:
 | --- | --- | --- |
 | `"np"` (default) | `audios` | list of float32 numpy waveforms in `[-1, 1]` |
 | `"pt"` | `audio_values` | `[B, num_samples]` tensor |
-| `"latent"` | `latents` | `[B, 8, 256, 16]` scaled latents (no VAE/vocoder) |
+| `"latent"` | `latents` | `[B, 8, 256, 16]` scaled latents (skips VAE/vocoder) |
 
 ### Precomputed T5 states
 
@@ -286,13 +444,6 @@ out = model.generate(
 v = model(latents, timesteps, encoder_hidden_states, encoder_attention_mask).sample
 ```
 
-### CLI (from the conversion package)
-
-```bash
-python qadit_hf/generate.py --model ./qadit-export \
-    --prompt "Rain falls on a metal roof" --out rain.wav
-```
-
 ---
 
 ## Precision and devices
@@ -306,11 +457,9 @@ Keep T5 / VAE / vocoder in float32 (FLAN-T5 overflows easily in fp16).
 ## Important details
 
 - `config.latent_scale` (**0.9503493**) must match training precompute.
-  `generate` divides by it before VAE decode — change it and the vocoder path
-  detunes.
+  `generate` divides by it before VAE decode.
 - Every sample is fixed length: **10.24 s @ 16 kHz**.
-- `repa_layer` exists for fine-tuning with the same REPA recipe; inference
-  ignores it.
+- `repa_layer` exists for REPA fine-tuning; inference ignores it.
 - Sampling always uses the **EMA** weights packaged here.
 
 ---
@@ -328,38 +477,40 @@ generation, or safety-critical audio.
 - ~24k steps on ~45k AudioCaps clips — undertrained vs public SOTA systems
 - Weak on speech, music, and densely described scenes
 - Inherits caption biases and coverage holes of AudioCaps
-- Generated audio can be quiet or coarse at low step counts; prefer the
-  default 50 DDIM steps for demos
-
-**Broader impacts:** same class of risks as other generative audio models
-(misleading media, copyright-adjacent imitation). Publish and use accordingly.
+- Prefer the default **50** DDIM steps for demos; low step counts sound coarse
 
 ---
 
-## Citation / links
+## Research artifact — how to improve this
 
-If this lab note or checkpoint helped your own from-scratch run, a link back
-to QuarkML is appreciated.
+This release is a **research artifact**, not a production host model. The
+architecture and sampling path are solid enough to build on; the ceiling is
+mostly data and compute:
+
+1. **Train longer** — continue past 24k steps with the same recipe (or lower LR).
+2. **Scale the dataset** — mix in larger captioned audio corpora beyond AudioCaps.
+3. **Retune sampling** — CFG scale, DDIM step count, and prompt formatting.
+4. **Keep measuring** — log diffusion loss, REPA loss, and listening tests.
+
+Those levers will move quality more than inventing a new backbone for this size
+of model. Contributions and longer runs are welcome; treat this Hub page as a
+reproducible baseline, not a finished product.
+
+---
+
+## Citation
 
 ```bibtex
-@misc{qadit_quarkml,
-  title        = {QaDiT: A From-Scratch Text-to-Audio Latent Diffusion Transformer},
+@misc{qadit2026,
+  title        = {QaDiT: A Text-to-Audio Latent Diffusion Transformer},
   author       = {Sidharth GN},
   year         = {2026},
-  howpublished = {\url{PLACEHOLDER_WEBSITE_POST}},
-  note         = {Code: PLACEHOLDER_GITHUB_REPO ; Weights: PLACEHOLDER_HF_MODEL}
+  note         = {Research artifact. Weights and transformers remote-code loading.}
 }
 ```
 
-| Resource | URL |
+| Resource | |
 | --- | --- |
-| Website | PLACEHOLDER_WEBSITE |
-| This build’s article | PLACEHOLDER_WEBSITE_POST |
-| GitHub (train + sample) | PLACEHOLDER_GITHUB_REPO |
-| Hugging Face model | PLACEHOLDER_HF_MODEL |
-| Dataset | https://huggingface.co/datasets/OpenSound/AudioCaps |
-
----
-
-*Built and published in the open as a QuarkML lab notebook entry — code, weights,
-numbers, and the messy middle included.*
+| Dataset | [OpenSound/AudioCaps](https://huggingface.co/datasets/OpenSound/AudioCaps) |
+| VAE / vocoder | [cvssp/audioldm-s-full-v2](https://huggingface.co/cvssp/audioldm-s-full-v2) |
+| Text encoder | [google/flan-t5-large](https://huggingface.co/google/flan-t5-large) |