initial

20260608_STREAM_DUMP_DEBUG.md

@@ -0,0 +1,160 @@
+# Stream dump — developer debug recording (FR 0.1)
+
+<!-- doc-meta:start -->
+| Field | Value |
+|---|---|
+| Author | Anton Afanasyeu |
+| Revision | R1 |
+| Creation date | 2026-06-08 |
+| Last modification date | 2026-06-08 |
+| Co-authored |  |
+| Severity | medium |
+| State | postponed |
+| Document type | technical |
+<!-- doc-meta:end -->
+
+\newpage
+\newpage
+
+---
+
+
+_Emergency debug — not an alpha release blocker. Enables 6.5 (audio lag) and 6.6 analysis._
+
+**Parent:** [20260608_ALPHA_PRIORITIES.md](20260608_ALPHA_PRIORITIES.md) §0.1
+
+---
+
+---
+
+---
+
+---
+
+
+---
+
+
+---
+
+---
+
+
+---
+
+## Table of contents
+
+<!-- toc -->
+- [Goals](#goals)
+- [Modes 0.1.1 vs 0.1.2](#modes-011-vs-012)
+- [Archive format](#archive-format)
+- [meta.json schema](#metajson-schema)
+- [Wire frame format (raw files)](#wire-frame-format-raw-files)
+- [Android implementation plan](#android-implementation-plan)
+- [Visualization / 0.1.3](#visualization-013)
+- [Tests](#tests)
+<!-- /toc -->
+
+**Documentation index:** [README.md](README.md)
+
+---
+
+## Goals
+
+- Record **elementary** encoded streams during an active cast session (sender first; receiver optional later).
+- Produce analyst-friendly bundles compatible with session stats tooling (0.1.3).
+- Dev-only; default **off**; bounded disk (e.g. 100 MB or 5 min).
+
+---
+
+## Modes 0.1.1 vs 0.1.2
+
+| Mode | ID | Content | Use |
+|------|-----|---------|-----|
+| **Structured** | 0.1.1 | Raw annex-B / ADTS-style with rich `meta.json` | Preferred for graphs replay |
+| **Raw quick** | 0.1.2 | Same files, minimal meta, no zip compression of streams | Fastest path to ship |
+
+Both use the **same archive naming**; only `record_mode` and optional fields differ.
+
+---
+
+## Archive format
+
+```text
+{filesDir}/stream_dumps/20260608_120422_sess_record.zip
+  meta.json
+  20260608_audio_stream.raw
+  20260608_video_stream.raw
+```
+
+Pull via `adb pull` or share intent from dev settings.
+
+---
+
+## meta.json schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `schema_version` | int | `1` |
+| `session_id` | string | `yyyyMMdd_HHmmss` |
+| `role` | string | `sender` \| `receiver` |
+| `record_mode` | string | `raw_elementary` \| `compressed_wire` (future) |
+| `started_at_epoch_ms` | long | |
+| `ended_at_epoch_ms` | long | |
+| `video` | object? | absent if audio-only |
+| `audio` | object? | absent if video-only |
+| `cast_settings_snapshot` | object | transport, protection, codecs |
+
+Per-stream object:
+
+| Field | Description |
+|-------|-------------|
+| `mime` | e.g. `video/avc`, `audio/mp4a-latm` |
+| `file` | basename inside zip |
+| `format` | `length_prefixed` — see below |
+| `frame_count` | int |
+| `sample_rate` / `channels` | audio |
+| `width` / `height` | video |
+| `csd0_hex` / `csd1_hex` | codec config (video) |
+
+---
+
+## Wire frame format (raw files)
+
+Each frame in `.raw`:
+
+```text
+[4 bytes BE length][payload bytes]
+```
+
+Payload = same bytes as `CastProtocol` audio/video frame body (after codec). PTS optional in meta sidecar or future v2 header.
+
+---
+
+## Android implementation plan
+
+| Step | Component |
+|------|-----------|
+| 1 | `AppPreferences.KEY_DEV_STREAM_DUMP` |
+| 2 | `StreamDumpWriter` — thread-safe append, rotate on session end |
+| 3 | Hook `CastSendPump` or encoder callbacks when flag on |
+| 4 | On `ScreenCastService` stop → finalize zip + `meta.json` |
+| 5 | Dev settings UI: toggle + “Open dumps folder” |
+
+**No new native deps** if Java-only zip (`java.util.zip`).
+
+---
+
+## Visualization / 0.1.3
+
+| Tool | Update |
+|------|--------|
+| `SessionStatsRecorder` / graphs ingest | Accept `meta.json` + frame counts |
+| Future offline decoder script | `scripts/decode_stream_dump.py` (TBD) |
+
+---
+
+## Tests
+
+- `StreamDumpWriterTest` — length-prefix round-trip, zip contains expected names
+- Manual: cast 30s with dump on → pull zip → verify `frame_count` > 0