pocketstation 1.0.0

Source-aware desktop audio Session SDK
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# PocketStation

PocketStation is a local-first Rust capture primitive for turning one permitted
desktop application and one microphone into independent, source-aware live
stems that can be observed, fanned out, transported, and recorded.

```text
application + microphone
          ↓
independent timed stems
          ↓
application callback + example transport + multistem recording
```

The product ships as one Cargo package, `pocketstation`. Its internal engine,
capture backends, graph, runtime, recording, codec, timing, observations, and C
projection are modules of that package. The native deliverable is
`libpocketstation`; C consumers include `pocketstation.h`.

```toml
[dependencies]
pocketstation = "1.0.0"
```

## Public Surface

The supported Rust entry point is `pocketstation::Session`. The narrow contract
selects an application and microphone, starts capture, receives each stem
independently, observes lifecycle/errors, stops, and receives recording
outcomes. Provider and transport integrations belong in examples or external
packages, not in the engine.

The `internal-testing` Cargo feature exposes implementation types only to
repository-owned conformance fixtures, the CLI, and the neutral benchmark. It
is not a supported application API.

The extension surface is open rather than provider-named:

- `SourceFactory` / `SourceDriver` add externally owned audio or typed sources;
- `Operator` manifests declare stable named input/output ports;
- `EndpointDriverFactory` owns external destinations;
- `Stream<T>` gives Rust compile-time composition while `SignalSpec` and schema
  remain the runtime, C, sidecar, and other-language identity;
- the versioned bounded sidecar protocol lets managed-language processes extend
  the one engine without executing managed code on audio callbacks.

See [the documentation index](docs/README.md) and
[extension guide](docs/guides/extensions.md).

## Internal Ownership

| Module | Responsibility |
|---|---|
| `session` | Public lifecycle, composition, cancellation, polling, and outcomes |
| `frame` | Buffers, source/stem identity, timestamps, sequence, and lineage |
| `timing` | Clock-domain estimation and correction |
| `graph` | Open signal/operator/endpoint contracts, compiler, and plan |
| `runtime` | Execution, bounded Bridges, fan-out, drops, and observations |
| `capture` | Capture contracts and macOS/Windows/Linux implementations |
| `endpoint` | Open destination lifecycle and registration |
| `recording` | Concrete aligned multistem recording |
| `codec` | Codec behavior and compatibility ABI implementation |
| `abi` | C projection of the same Session and codec implementation |

Advanced denoise, echo cancellation, voice activity detection, inference, and
other product algorithms are external Operators rather than built-in Core
modules.

Metrics are operational observations owned by `runtime`; they are not a
separate product subsystem or crate.

## Artifact Names

- Rust: `pocketstation`
- C header: `pocketstation.h`
- Unix library: `libpocketstation.a`, `libpocketstation.dylib`, or
  `libpocketstation.so`
- Windows library: `pocketstation.dll` / `pocketstation.lib`
- Apple framework target: `PocketStation.framework`

Retained `pks_*` function symbols are temporary binary compatibility only.
There are no separately marketed `*-core` or `*-c` products.

## Development

```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo test --all-targets --all-features --locked
cargo build --release --example product_quickstart --locked
bash scripts/check_protocol.sh
```

Passing component tests is not a real-device claim. Product acceptance still
requires the real-path permission, recovery, destination-failure, latency,
drop-rate, soak, integrity, and clean-checkout evidence defined by the factory
operating contract and execution registry.