lgtv_audio_cap/docs/development.md

# Building, testing and publishing

## What you need

| For | Install |
| --- | --- |
| the native service | the [openlgtv buildroot NDK](https://github.com/openlgtv/buildroot-nc4/releases), `arm-webos-linux-gnueabi_sdk-buildroot` |
| packaging | `npm install -g @webosose/ares-cli` |
| the tests | a host C compiler, Python 3, Node (optional: `flatbuffers`, `jsdom`) |

Unpack the NDK and relocate it once:

```sh
tar xf arm-webos-linux-gnueabi_sdk-buildroot.tar.gz -C "$HOME"
"$HOME/arm-webos-linux-gnueabi_sdk-buildroot/relocate-sdk.sh"
```

Register the TV with ares once, using the Homebrew Channel's ssh (port 9922,
root):

```sh
ares-setup-device --add tv \
  --info "{'host':'192.168.1.20','port':9922,'username':'root'}"
```

## Build and deploy

```sh
./tools/build.sh            # cross-compile, stage, package -> out/*.ipk
./tools/build.sh install    # ares-install on device "tv"
./tools/build.sh launch
./tools/build.sh logs
```

`DEVICE=livingroom ./tools/build.sh install` targets a different device;
`WEBOS_SDK=/opt/webos-sdk ./tools/build.sh` a differently placed NDK.

The same commands exist as npm scripts (`npm run build`, `npm run deploy`, …)
if that is more your habit.

### What the packaging step does

`ares-package` takes two directories:

```text
build/stage/app       frontend/, minus js/mock.js and its <script> tag
build/stage/service   servicefiles/ plus the compiled audiocap-service
```

The service is declared native in `servicefiles/services.json`
(`"engine": "native"`), which is what makes webOS exec the binary rather than
look for a Node entry point.

## Tests

```sh
./test/run-tests.sh
```

Everything runs on the host — no TV involved:

| Suite | What it proves |
| --- | --- |
| syntax check | `service.c` and `main.c` compile against stub Luna/glib headers |
| `verify_flatbuf.py` | the hand-rolled FlatBuffers encoder matches what the official Python runtime decodes — union tags, defaults, vector contents |
| `verify_rtp.py` | the RTP sink and `host/lgtv-audiocap-receiver.py` agree: header layout, sequencing, timestamps, big-endian payload, MTU, and the SDP text |
| `engine_smoke.c` | capture → DSP → fan-out → sockets, including all 44 bytes of the WAV header and the status document |
| `ui_smoke.js` | the real `index.html` loaded in jsdom and driven like a remote |

The two optional dependencies:

```sh
python3 -m venv /tmp/fbvenv && /tmp/fbvenv/bin/pip install flatbuffers
npm install          # jsdom
```

Without them those two suites print SKIP and the rest still runs.

To open the UI in a desktop browser — `js/mock.js` stands in for the Luna bus:

```sh
npm run serve      # http://localhost:8000
```

## Publishing to the Homebrew Channel

1. Bump `version` in `frontend/appinfo.json`, `servicefiles/package.json` and
   `package.json`.
2. `./tools/build.sh` and test the ipk on a real set.
3. Attach the ipk and `frontend/assets/icon.png` to a release.
4. Generate the manifest and attach that too:

   ```sh
   python3 tools/make-manifest.py \
     --base-url https://github.com/you/lgtv-audio-cap/releases/download/v1.0.0
   ```

5. Submit the manifest URL to [webosbrew/repo](https://github.com/webosbrew/repo).

The manifest sets `"rootRequired": true`, which tells the Homebrew Channel the
service needs elevating. The app can also do it on demand — *System → Grant root
access* runs the Channel's `elevate-service`.

## How the service is put together

```text
main.c        registers on the bus, runs the glib loop
service.c     the Luna methods and the status subscription
engine.c      the capture thread: read a block, analyse it, hand it to every sink
config.c      load/merge/atomic-save of config.json
dsp.c         peak/RMS envelopes and the 16-band analysis
capture/      one file per backend, all dlopen-based
sinks/        one file per output
net/          RTP, FlatBuffers, the shared stream server
common/       JSON, logging, ring buffer, audio format
```

Three rules hold the design together:

**One format inside.** Everything between a backend and a sink is interleaved
signed 16-bit little-endian PCM at the configured rate. Backends convert on the
way in, sinks convert on the way out. Nothing in the middle branches on sample
type.

**Sinks must never block.** The engine calls every sink from the capture thread,
in order, and a sink that stalls stalls capture. Anything that can wait — a TCP
client that stopped reading, a HyperHDR host that is switched off — buffers
internally and drops the oldest audio instead. The Flatbuffers sink connects
non-blockingly and finishes the handshake on later blocks; sends are bounded to
200 ms.

**Audio libraries are `dlopen`ed, never linked.** A TV without `libpulse` must
still run the ALSA backend, and one with neither must still run the test tone
and start up cleanly. `ldd` on the binary shows glib, luna-service2, libc — no
audio.

### Adding a sink

1. Write `native/src/sinks/sink_yours.c` with an `open` that reads its own key
   out of the settings object, plus `write`, `status` and `close`.
2. Define `const sink_driver_t sink_driver_yours` at the bottom and declare it
   in `sinks/sink.h`.
3. Add it to the table in `sinks/sink.c` and to `DEFAULTS_JSON` in `config.c`.
4. Add its fields to `SINK_FIELDS` in `frontend/js/app.js`.

The UI needs nothing else: it builds the Outputs panel from `listSinks`.

### Adding a capture backend

The same shape in `native/src/capture/`, with an `available()` that answers
honestly on a TV that lacks the library, and an optional `describe()` that adds
its own fields to the diagnostics.