Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/site.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ jobs:
run: |
node tools/device-acceptance/validate-report.mjs \
tools/device-acceptance/fixtures/report-template-v1.json
node tools/device-acceptance/validate-report.mjs \
tools/device-acceptance/fixtures/android-speaker-microphone-template-v1.json
node tools/device-acceptance/test-validator.mjs
- name: Verify English and Russian document pairs
run: |
Expand All @@ -45,11 +47,13 @@ jobs:
"docs/research/acoustic-2-measurement-sources.md:docs/research/acoustic-2-measurement-sources_RU.md"
"docs/research/device-acceptance-sources.md:docs/research/device-acceptance-sources_RU.md"
"docs/research/live-audio-adapter-sources.md:docs/research/live-audio-adapter-sources_RU.md"
"docs/research/android-live-audio-adapter-sources.md:docs/research/android-live-audio-adapter-sources_RU.md"
"docs/operations/device-acceptance.md:docs/operations/device-acceptance_RU.md"
"spec/protocol-v1.md:spec/protocol-v1_RU.md"
"spec/acoustic-1.md:spec/acoustic-1_RU.md"
"spec/acoustic-2.md:spec/acoustic-2_RU.md"
"spec/live-audio-adapter-v1.md:spec/live-audio-adapter-v1_RU.md"
"spec/android-live-audio-adapter-v1.md:spec/android-live-audio-adapter-v1_RU.md"
)
for pair in "${pairs[@]}"; do
source_path="${pair%%:*}"
Expand Down
2 changes: 2 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,12 @@ This directory holds the human-readable technical documentation for AudioModem.
| Research | [Acoustic-2 measurement sources](research/acoustic-2-measurement-sources.md) | [Источники измерений Acoustic-2](research/acoustic-2-measurement-sources_RU.md) | Controlled PCM transform and timing-acquisition constraints |
| Research | [Device-acceptance sources](research/device-acceptance-sources.md) | [Источники device acceptance](research/device-acceptance-sources_RU.md) | Reproducible evidence, metadata and privacy constraints |
| Research | [Live-audio adapter sources](research/live-audio-adapter-sources.md) | [Источники live-audio adapter](research/live-audio-adapter-sources_RU.md) | Session, permission, focus and lifecycle constraints |
| Research | [Android live-audio adapter sources](research/android-live-audio-adapter-sources.md) | [Источники Android live-audio adapter](research/android-live-audio-adapter-sources_RU.md) | First-target decision and Android/PipeWire route constraints |
| Specification | [ADLP v1](../spec/protocol-v1.md) | [ADLP v1 на русском](../spec/protocol-v1_RU.md) | Normative wire object and WAV bootstrap carrier |
| Specification | [Acoustic-1](../spec/acoustic-1.md) | [Acoustic-1 на русском](../spec/acoustic-1_RU.md) | Experimental B-FSK carrier and compatibility boundary |
| Specification | [Acoustic-2](../spec/acoustic-2.md) | [Acoustic-2 на русском](../spec/acoustic-2_RU.md) | Experimental controlled PCM measurement contract |
| Specification | [Live-audio adapter v1](../spec/live-audio-adapter-v1.md) | [Live-audio adapter v1 на русском](../spec/live-audio-adapter-v1_RU.md) | Typed unavailable-first contract for future routes |
| Specification | [Android live-audio adapter v1](../spec/android-live-audio-adapter-v1.md) | [Android live-audio adapter v1 на русском](../spec/android-live-audio-adapter-v1_RU.md) | Draft foreground Android route lifecycle and acceptance constraints |

## Translation convention

Expand Down
2 changes: 2 additions & 0 deletions docs/README_RU.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,12 @@
| Research | [Acoustic-2 measurement sources](research/acoustic-2-measurement-sources.md) | [Источники измерений Acoustic-2](research/acoustic-2-measurement-sources_RU.md) | Ограничения controlled PCM transforms и timing acquisition |
| Research | [Device-acceptance sources](research/device-acceptance-sources.md) | [Источники device acceptance](research/device-acceptance-sources_RU.md) | Ограничения reproducible evidence, metadata и privacy |
| Research | [Live-audio adapter sources](research/live-audio-adapter-sources.md) | [Источники live-audio adapter](research/live-audio-adapter-sources_RU.md) | Ограничения session, permission, focus и lifecycle |
| Research | [Android live-audio adapter sources](research/android-live-audio-adapter-sources.md) | [Источники Android live-audio adapter](research/android-live-audio-adapter-sources_RU.md) | Решение о first target и Android/PipeWire route constraints |
| Specification | [ADLP v1](../spec/protocol-v1.md) | [ADLP v1 на русском](../spec/protocol-v1_RU.md) | Нормативный wire object и WAV bootstrap carrier |
| Specification | [Acoustic-1](../spec/acoustic-1.md) | [Acoustic-1 на русском](../spec/acoustic-1_RU.md) | Экспериментальный B-FSK carrier и граница compatibility |
| Specification | [Acoustic-2](../spec/acoustic-2.md) | [Acoustic-2 на русском](../spec/acoustic-2_RU.md) | Экспериментальный controlled PCM measurement contract |
| Specification | [Live-audio adapter v1](../spec/live-audio-adapter-v1.md) | [Live-audio adapter v1 на русском](../spec/live-audio-adapter-v1_RU.md) | Typed unavailable-first contract для будущих routes |
| Specification | [Android live-audio adapter v1](../spec/android-live-audio-adapter-v1.md) | [Android live-audio adapter v1 на русском](../spec/android-live-audio-adapter-v1_RU.md) | Draft foreground Android route lifecycle и acceptance constraints |

## Правило поддержки перевода

Expand Down
6 changes: 3 additions & 3 deletions docs/implementation-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,11 +54,11 @@ Text must not be silently overloaded to represent an image or file. The first bo

### Stage E — Add one live-audio platform adapter

Only after the Flutter shell and PCM contract are stable should work begin on one platform. The initial target must be selected explicitly in a route RFC; it will specify plugin/native APIs, session/permission policy, interruption behavior, one route, buffer boundaries, diagnostics and stop/dispose semantics. The adapter starts as experimental and defaults to unavailable outside its declared scope.
After the Flutter shell and PCM contract are stable, platform work begins with one route RFC. The first selected design target is **Android API 26+ foreground playback/capture**, documented in the [Android live-audio adapter v1 RFC](../spec/android-live-audio-adapter-v1.md). It specifies native APIs, session/permission policy, interruption behavior, default-route boundary, buffer/format checks, diagnostics and stop/dispose semantics. The adapter remains unavailable until the RFC and acceptance change receive review; it will remain unavailable outside its declared scope.

| Entry condition | Work product | Exit gate | Explicit non-claim |
| --- | --- | --- | --- |
| Route RFC, test method and target build are approved. | One adapter, unit/integration tests and a privacy-preserving device-acceptance template. | The adapter reports only its declared availability; a reviewed physical-route report exists for the exact scope. | One observation is not a broad compatibility, range, Bluetooth or radio claim. |
| Android route RFC, machine-checked acceptance extension and target build are approved. | One Android adapter, unit/integration tests and real privacy-preserving physical-route reports. | The adapter reports only its declared availability; a reviewed physical-route report exists for the exact scope. | One observation is not a broad compatibility, range, Bluetooth or radio claim. |

### Stage F — Publish evidence, compatibility and releases

Expand All @@ -76,4 +76,4 @@ After repeated reviewed evidence, compatibility documentation may describe the e

## Immediate execution order

The active implementation milestone is **Stage B preparation**. First, the project will define a small transfer-task model and fake bridge fixture for the existing text/WAV workflow. Next, the Flutter shell will be separated from its current page-local state so that widget tests can drive send, receive, cancellation, unavailable and rejection paths without native audio. The existing Rust bridge and golden fixtures stay unchanged until the shell contract identifies a concrete missing typed value.
The active milestone is **Stage E Android route design review**. The repository now has a bilingual Android foreground RFC, research decision, unexecuted reporting template and validator extension that requires exact v1 PCM, permission, focus, stop and privacy fields for future Android speaker-to-microphone measurements. The next implementation change may add a native Android adapter only after this design slice is reviewed and merged. It must begin unavailable outside Android API 26+ foreground scope and must not create a physical-route claim without real reviewed observations.
6 changes: 3 additions & 3 deletions docs/implementation-plan_RU.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,11 +56,11 @@ Text не должен молча использоваться как image ил

### Stage E — Добавить один live-audio platform adapter

Только после стабилизации Flutter shell и PCM contract начинается работа на одной platform. Initial target выбирается явно в route RFC; он задаёт plugin/native APIs, session/permission policy, interruption behavior, один route, buffer boundaries, diagnostics и stop/dispose semantics. Adapter начинается как experimental и defaults to unavailable вне declared scope.
После стабилизации Flutter shell и PCM contract platform work начинается с одного route RFC. Первый selected design target — **Android API 26+ foreground playback/capture**, описанный в [Android live-audio adapter v1 RFC](../spec/android-live-audio-adapter-v1_RU.md). Он задаёт native APIs, session/permission policy, interruption behavior, default-route boundary, buffer/format checks, diagnostics и stop/dispose semantics. Adapter остаётся unavailable до review RFC и acceptance change; вне declared scope он останется unavailable.

| Entry condition | Work product | Exit gate | Explicit non-claim |
| --- | --- | --- | --- |
| Route RFC, test method и target build утверждены. | Один adapter, unit/integration tests и privacy-preserving device-acceptance template. | Adapter сообщает только declared availability; существует reviewed physical-route report для exact scope. | Одно observation не является broad compatibility, range, Bluetooth или radio claim. |
| Android route RFC, machine-checked acceptance extension и target build утверждены. | Один Android adapter, unit/integration tests и real privacy-preserving physical-route reports. | Adapter сообщает только declared availability; существует reviewed physical-route report для exact scope. | Одно observation не является broad compatibility, range, Bluetooth или radio claim. |

### Stage F — Публикация evidence, compatibility и releases

Expand All @@ -78,4 +78,4 @@ Text не должен молча использоваться как image ил

## Ближайший порядок исполнения

Активный implementation milestone — **подготовка Stage B**. Сначала проект определит small transfer-task model и fake bridge fixture для existing text/WAV workflow. Затем Flutter shell будет отделена от текущего page-local state, чтобы widget tests могли управлять send, receive, cancellation, unavailable и rejection paths без native audio. Existing Rust bridge и golden fixtures остаются без изменений, пока shell contract не выявит конкретное отсутствующее typed value.
Активный milestone — **Stage E Android route design review**. В repository теперь есть bilingual Android foreground RFC, research decision, unexecuted reporting template и validator extension, требующий exact v1 PCM, permission, focus, stop и privacy fields для future Android speaker-to-microphone measurements. Next implementation change может добавить native Android adapter только после review и merge этого design slice. Он должен начинаться unavailable вне Android API 26+ foreground scope и не может создавать physical-route claim без real reviewed observations.
16 changes: 15 additions & 1 deletion docs/operations/device-acceptance.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Device-acceptance protocol

**Status:** Experimental operations contract · **Last reviewed:** 2026-08-20 · **English (canonical)** · [Русский](device-acceptance_RU.md)
**Status:** Experimental operations contract · **Last reviewed:** 2026-08-21 · **English (canonical)** · [Русский](device-acceptance_RU.md)

This protocol governs future evidence for a live audio route. It does **not** make any platform, device, cable, Bluetooth path, radio interface or Acoustic-1/Acoustic-2 experiment supported. A single report is an observation awaiting review; it is not a performance claim.

Expand Down Expand Up @@ -42,6 +42,20 @@ node tools/device-acceptance/validate-report.mjs \

The committed fixture above is intentionally an **unexecuted template**, not a device result. A contributor creates a new measurement sidecar only after obtaining real hardware observations.

## Android foreground v1 extension

The [Android foreground live-audio adapter RFC](../../spec/android-live-audio-adapter-v1.md) selects the first experimental platform-route design. It does not enable a route. The generic schema and validator now reserve `adapter_observation` for a future `measurement` whose route is exactly `speaker_microphone` and whose source and sink platforms are both `android`. That record must declare the reviewed adapter contract, Android API level of at least 26, playback/capture operation, requested and effective **48 kHz / mono / PCM16 LE** format, granted microphone permission, granted or delayed-then-granted focus, route-change observation, stop-without-auto-resume policy and discarded raw PCM.

This extension is deliberately narrow. It neither permits an unexecuted template to include device/evidence fields nor changes requirements for every other route. It rejects an Android observation with a mismatched effective format or any value that would imply raw audio retention or auto-resume.

```bash
node tools/device-acceptance/validate-report.mjs \
tools/device-acceptance/fixtures/android-speaker-microphone-template-v1.json
node tools/device-acceptance/test-validator.mjs
```

The Android template is still unexecuted. It contains no device, run, outcome, permission or route observation and must not be cited as an Android measurement.

## Decision gates

| Gate | Required evidence | Permitted label |
Expand Down
16 changes: 15 additions & 1 deletion docs/operations/device-acceptance_RU.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[English (canonical)](device-acceptance.md) · **Русский перевод**

> **Translation of:** [docs/operations/device-acceptance.md](device-acceptance.md). **Last synced:** 2026-08-20. Английский оригинал определяет contract implementation.
> **Translation of:** [docs/operations/device-acceptance.md](device-acceptance.md). **Last synced:** 2026-08-21. Английский оригинал определяет contract implementation.

Этот protocol регулирует будущие evidence для live audio route. Он **не** делает supported ни платформу, ни устройство, ни кабель, ни Bluetooth path, ни radio interface, ни Acoustic-1/Acoustic-2 experiment. Один report — observation, ожидающее review, а не performance claim.

Expand Down Expand Up @@ -44,6 +44,20 @@ node tools/device-acceptance/validate-report.mjs \

Committed fixture выше намеренно является **unexecuted template**, а не device result. Новый measurement sidecar создаётся только после получения реальных hardware observations.

## Android foreground v1 extension

[Android foreground live-audio adapter RFC](../../spec/android-live-audio-adapter-v1_RU.md) выбирает first experimental platform-route design. Он не включает route. Generic schema и validator теперь резервируют `adapter_observation` для будущего `measurement`, где route точно `speaker_microphone`, а source и sink platforms — оба `android`. Такой record обязан указать reviewed adapter contract, Android API level не ниже 26, playback/capture operation, requested и effective **48 kHz / mono / PCM16 LE** format, granted microphone permission, granted или delayed-then-granted focus, route-change observation, stop-without-auto-resume policy и discarded raw PCM.

Extension намеренно узкий. Он не разрешает unexecuted template включать device/evidence fields и не изменяет требования для остальных routes. Он отклоняет Android observation с mismatched effective format или любым value, предполагающим raw audio retention либо auto-resume.

```bash
node tools/device-acceptance/validate-report.mjs \
tools/device-acceptance/fixtures/android-speaker-microphone-template-v1.json
node tools/device-acceptance/test-validator.mjs
```

Android template остаётся unexecuted. В нём нет device, run, outcome, permission или route observation и его нельзя приводить как Android measurement.

## Decision gates

| Gate | Required evidence | Permitted label |
Expand Down
4 changes: 2 additions & 2 deletions docs/reference/platform-support.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Platform support

**Last reviewed:** 2026-08-20 · **English (canonical)** · [Русский](platform-support_RU.md)
**Last reviewed:** 2026-08-21 · **English (canonical)** · [Русский](platform-support_RU.md)

AudioModem keeps Flutter runners for Android, iOS, Windows, macOS, Linux and Web in one application directory. The Rust workspace supplies the container and WAV bootstrap codec. This structure is an implementation target, not a claim that every platform currently supports every route.

## Status matrix

| Platform | Flutter runner | Rust/WAV integration | Local WAV workflow | Live audio | Notes |
| --- | --- | --- | --- | --- | --- |
| Android | Scaffolded | Bridge source integrated; target build/run not verified | Source implementation; target dialog not verified | Planned | Requires target build, permission and route-adapter acceptance tests. |
| Android | Scaffolded | Bridge source integrated; target build/run not verified | Source implementation; target dialog not verified | Draft experimental design | [Foreground adapter RFC](../../spec/android-live-audio-adapter-v1.md) and validator extension exist; target build, permission behavior, adapter and route evidence remain unverified. |
| iOS | Scaffolded | Bridge source integrated; target build/run not verified | Source implementation; target dialog not verified | Planned | Requires target build, permission and route-adapter acceptance tests. |
| Windows | Scaffolded | Bridge source integrated; target build/run not verified | Source implementation; target dialog not verified | Planned | Requires native device enumeration and routing tests. |
| macOS | Scaffolded | Bridge source integrated; target build/run not verified | Source implementation; target dialog not verified | Planned | Requires native device enumeration and routing tests. |
Expand Down
Loading
Loading