Skip to content

Embeddable place: listening port, file voice source, heartbeat stop - #55

Merged
nevyn merged 8 commits into
mainfrom
feature/demo-office
Oct 15, 2026
Merged

nevyn merged 8 commits into
mainfrom
feature/demo-office

Conversation

@nevyn

@nevyn nevyn commented Sep 18, 2026 •

Copy link
Copy Markdown
Member

Why

KojaApp is getting a demo office for onboarding: it runs a PlaceServer inside the app, plus an in-process alloapp whose six avatars speak pre-recorded voice tracks. Three things were missing for an embedder. Plan: https://app.notion.com/p/25d383c5f055807e8584e97dd0636a61

What

  • PlaceServer.listeningPort: the port the HTTP listener bound, so httpPort: 0 is usable. TestPlace now uses it, which removes its reserve-then-release port race.
  • AlloAudio.VoiceRecording (moved out of voicedemo, now public) and VoiceRecordingPlayer: one 20 ms clock derives the frames due from elapsed time and sends them for every recording in the same tick, so recordings started together stay in step. A late tick catches up by at most 5 frames and drops the rest. voicedemo uses both instead of its private copy.
  • PlaceServer.stop() stops its HeartbeatTimer, and a stopped timer refuses to re-arm. Before, a stopped place kept a 1 Hz beat and, through the timer's closure, the whole place alive.

Additive API only; no wire change.

How verified

  • swift build passes. New suites pass: VoiceRecordingTests, VoiceRecordingPlayerTests, EphemeralPortTests, HeartbeatTimerTests.firesNothingAfterStop.
  • voicedemo with VOICEDEMO_WAV against a local AlloPlace -b 127.0.0.1: 246 and 236 frames per 5 s window against a target of 250 on a machine at load ~100 (the shortfall is the catch-up cap).
  • End to end in KojaApp: six streams from one client, heard and shown as speaking rings in the visor.

Still owed

The full parallel swift test failed on the development machine in CondemnedClientTests.fatalErrorResponseSaysSoAndTheHangupWaitsForIt and two NoOpWriteTests cases. They pass in isolation and with this PR's suites skipped one of them still fails, so they look like wall-clock assertions that a shared test process cannot guarantee; not yet confirmed against an untouched main on an idle machine. CI on this PR is the first clean data point.

🤖 Generated with Claude Code

Review guide

https://files.d.nevyn.dev/k/f2a2c09f292bfeec/allonet2-55-demo-office.html

nevyn and others added 4 commits September 18, 2026 18:43
An embedded place can pass httpPort: 0 and let the OS pick a free port, but
nothing could read the result: PlaceServerHTTP.http and .port are private.
listeningPort passes FlyingFox's listeningAddress through, and is nil until
start() has bound the socket. The end-to-end harness uses it instead of
reserving a port and trusting that nothing else takes it in between.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
voicedemo's private Recording becomes AlloAudio.VoiceRecording, and the new
VoiceRecordingPlayer drives any number of recordings from one 20 ms clock, so
recordings started together stay in step for as long as the player runs - what
several puppets talking in one room need. Each tick sends what elapsed time
says is due rather than one frame per tick, so a late tick catches up; past
maximumCatchUp frames it drops the backlog, since a burst is discarded by the
receiver's jitter buffer anyway. voicedemo uses both, so there is one
implementation of reading a file onto a stream.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
PlaceServer.stop() left its HeartbeatTimer running, and the timer re-arms
itself after every sync, so an embedder that stopped a place kept a 1 Hz
beat, and through its closure the whole place, for the rest of the process.
stop() now stops the timer, and a stopped timer refuses to re-arm, which
also covers the sync that was in flight when stop() was called.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ts users

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 18, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-15T20:23:22.069002Z d96b638 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7e30dfffd8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

nevyn and others added 2 commits September 18, 2026 23:59
A disconnecting client's cleanup awaits the next beat, so stopping the
heartbeat in PlaceServer.stop() left those tasks waiting forever, holding
the clients and the server. stop() now finishes the sync stream, and
awaitNextSync() returns at once on a stopped timer. The timer's action
captures the place weakly, so a stopped place can deallocate.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
A codec has to be installed before start(), and onFrameSent runs on the
queue that start() and stop() wait for.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

guard file.framePosition > 0 else { throw error }

P2 Badge Propagate mid-file read failures instead of treating them as EOF

When a compressed or externally modified file produces a genuine decode or I/O error after at least one successful read, file.framePosition > 0 is also true, so this catch treats the failure as an early EOF, rewinds, and repeatedly plays the readable prefix. That silently corrupts playback instead of delivering the documented Failure.decodeFailed; only the specific premature-EOF condition should trigger looping, while other errors must be rethrown.

AGENTS.md reference: AGENTS.md:L30-L30

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

The docs said the backlog past maximumCatchUp is dropped. The player forgives
it instead: the recordings carry on from where they were, which is what
looping speech wants, and they stay in step because all of them pause alike.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Comment thread README.md Outdated
* `-p <port>` — TCP port for the HTTP listener (signalling, assets, dashboard; default 9080).
An app embedding `PlaceServer` rather than running this CLI can pass `httpPort: 0` to let the
OS pick a free port, and read it back from `PlaceServer.listeningPort` once `start()` has bound
the listener.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is narrating agent context. It should just be something like "pass httpPort: 0 to pick a free port, and read it back with PlaceServer.listeningPort after start()". No need to overcomplicate it.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d96b638: one sentence, as suggested. 🤖 Claude Fable 5.1

Comment thread Sources/AlloAudio/VoiceRecording.swift Outdated
/// start inside the same conversion pass, so the loop is sample-continuous at the seam and no
/// frame is ever short.
///
/// Use it to speak a file into a place - a test that needs speech to localise, or a demo avatar

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"or a demo avatar" narrating your context. Your specific use case is not interesting to the documentation reader.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d96b638: the sentence is gone, and the same narration in docs/voice.md went with it. 🤖 Claude Fable 5.1

Comment thread Sources/AlloAudio/VoiceRecording.swift Outdated
{
enum Failure: Error, CustomStringConvertible
/// Samples in one frame, the same 20 ms the wire carries.
public static let frameCount = DataChannelMediaStream.frameDuration

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What frame count? let chunkFrameCount or something to denote that it's the amount of frames that we'll be sending at a time, not like... the count of frames in a loaded file, or the max frame count, or whatever.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d96b638: chunkFrameCount, documented as the sample frames in one chunk nextFrame() returns. 🤖 Claude Fable 5.1

VoiceRecording.chunkFrameCount says what the number is: sample frames per
chunk nextFrame() returns, not frames in the file. The docs for the
recording, the player and the listening port describe the API, not who
first needed it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@nevyn
nevyn merged commit b919c37 into main Oct 15, 2026
3 checks passed
@nevyn
nevyn deleted the feature/demo-office branch October 15, 2026 21:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant