Native audio input proposal

Unofficial design discussion and implementation evidence for a low-level audio input capability in vercel-labs/native, with Zig and TypeScript app-core parity.

Status: issue proposal ready for maintainer discussion. No upstream issue has been posted and no implementation is claimed. Implementation remains blocked on the public contract.

Current conclusion

The most Native-shaped contribution is a built-in keyed Cmd stream, not Sub, an application-defined external effect, or browser media plumbing. It should list devices without prompting, start one host-owned input session, deliver bounded interleaved PCM16LE through one fixed structural Msg arm, report actual format/device/loss truth, stop with callback quiescence, and produce identical scripted transcripts under Node and the native host.

The likely defaults inferred from current code are documented separately from the safety requirements. Maintainers still own every public API and policy decision.

Repository map

• ISSUE.md — self-contained issue body suitable for upstream discussion.
• MAINTAINER_DECISIONS.md — likely answers to every open contract question, confidence, evidence, and fallback wording.
• DESIGN.md — architecture and non-negotiable safety invariants.
• IMPLEMENTATION_PLAN.md — T0–T6 ownership, dependencies, and pre-registered gates after agreement.
• EVIDENCE.md — current upstream status, code/PR evidence, and historical-prototype disposition.
• CONTRIBUTING.md — scope for discussion changes in this repository.

Upstream status

Source cutoff: 2026-07-15.

• main, HEAD, and release v0.5.1 resolve to f7aa92af6dcece250feba852af4d22e7f5429312.
• No public microphone/audio-input issue, PR, branch, or discussion was found.
• PR #119 makes TypeScript the default app-core tier and establishes byte-identical Node/native parity.
• PR #124 makes teardown lifetime a memory-safety contract.
• Open issue #131 and PR #132 explore bounded application-defined effects. That request/result mechanism is not a real-time audio-input substitute, but it may create file-level conflicts if merged before implementation begins.
• Issue #108 and PR #135 expose a low-sample- rate playback bug. Audio-input tests must therefore include 8, 16, 24, 44.1, and 48 kHz actual formats.

Historical prototype

The branch juanbermudez/native@codex/audio-input-stream-preview is v0.4.4-based reference evidence only. It explored useful device, borrowed- PCM, NullPlatform, macOS, and consent concepts, but it predates TypeScript app cores and lacks the required capability, actual-format, stale-session, and callback-quiescence guarantees. It must not be rebased or cherry-picked wholesale.

Scope boundary

This proposal covers a low-level input primitive and one truthful macOS system host. It does not cover encoded file creation, speech behavior, browser media, web-content control, duplex processing guarantees, background policy, simultaneous inputs, or additional OS host implementations.