nick/amethyst
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

nestsClient: pack 5 Opus frames per moq-lite group to dodge the prod stream cliff

Browse Source 
Production sweep against nostrnests.com cliffed at exactly 99 frames received
across every multi-frame scenario (frames200/400, 30s, 120s, etc.) when the
broadcaster opened one QUIC uni stream per Opus frame. The investigation in
nestsClient/plans/2026-05-01-quic-stream-cliff-investigation.md walks through
why the obvious "raise the stream cap" hypothesis didn't pan out (publisher.send
was never returning false past the cap, the local QuicConnection was already
seeing the relay extend MAX_STREAMS_UNI dynamically).

The same sweep showed sweep_frames_per_group_5 / _20 / _all delivering 100/100
frames cleanly. The cliff scales with stream-creation rate, not byte volume or
total stream count — so packing N frames per group (one uni stream per N frames
instead of per frame) bypasses whatever the underlying limit is.

NestMoqLiteBroadcaster:
  - Add framesPerGroup constructor param, default 5 (≈ 100 ms of audio per
    moq-lite group). Stream-creation rate drops from 50/sec to 10/sec, well
    below the production cliff threshold.
  - Counter resets after each endGroup; trailing partial group flushes its
    FIN on capture EOF so the listener doesn't sit on a half-open stream.

MoqLiteNestsSpeaker + connectNestsSpeaker:
  - Plumb framesPerGroup through to the broadcaster. Default flows from
    NestMoqLiteBroadcaster.DEFAULT_FRAMES_PER_GROUP so production callers
    get the mitigation without code changes; tests can override to 1 to
    keep their groupId-per-frame assertions.

Tests:
  - All harness interop tests (RoundTrip, LateJoin, MultiPeer, Mute,
    Unsubscribe, SpeakerClose, both Reconnecting variants) plus the prod
    NostrnestsProdAudioTransmissionTest now pass framesPerGroup = 1
    explicitly to preserve their per-frame group/object id assertions.
  - All :quic and :nestsClient JVM tests pass.

Trade-off: a brand-new subscriber that joins mid-broadcast picks up at the
next group boundary. With 5 frames/group the late-join initial gap is up
to 100 ms (perceptually inaudible for live audio). The previous wire shape
gave at most 20 ms.

Investigation plan for the underlying QUIC cliff lives in
nestsClient/plans/2026-05-01-quic-stream-cliff-investigation.md. The
attempted-then-reverted suspend/STREAMS_BLOCKED commit is summarised
under "Attempt 1" in that doc.
This commit is contained in:
Claude
2026-05-01 14:06:21 +00:00
parent 96a585a67e
commit 10ad69f1af
13 changed files with 333 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nestsClient/src/commonMain/kotlin/com/vitorpamplona/nestsclient/MoqLiteNestsSpeaker.kt
+8
View File
@@ -52,6 +52,13 @@ class MoqLiteNestsSpeaker internal constructor(
private val encoderFactory: () -> OpusEncoder,
private val scope: CoroutineScope,
private val mutableState: MutableStateFlow<NestsSpeakerState>,
/**
* How many Opus frames to pack into one moq-lite group / QUIC uni
* stream. Forwarded to [NestMoqLiteBroadcaster.framesPerGroup] —
* see that field's kdoc for the production stream-cliff rationale.
* Defaults to [NestMoqLiteBroadcaster.DEFAULT_FRAMES_PER_GROUP].
*/
private val framesPerGroup: Int = NestMoqLiteBroadcaster.DEFAULT_FRAMES_PER_GROUP,
) : NestsSpeaker {
override val state: StateFlow<NestsSpeakerState> = mutableState.asStateFlow()
@@ -81,6 +88,7 @@ class MoqLiteNestsSpeaker internal constructor(
encoder = encoderFactory(),
publisher = publisher,
scope = scope,
framesPerGroup = framesPerGroup,
)
broadcaster.start()
mutableState.value =
nestsClient/src/commonMain/kotlin/com/vitorpamplona/nestsclient/NestsConnect.kt
+9
View File
@@ -167,6 +167,11 @@ private fun failedListener(state: MutableStateFlow<NestsListenerState>): NestsLi
* Android passes `{ AudioRecordCapture() }`.
* @param encoderFactory builds an [OpusEncoder] (one per broadcast).
* Android passes `{ MediaCodecOpusEncoder() }`.
* @param framesPerGroup how many Opus frames to pack into one moq-lite
* group / QUIC uni stream. See
* [com.vitorpamplona.nestsclient.audio.NestMoqLiteBroadcaster.framesPerGroup]
* for the production stream-cliff rationale that motivates the
* default of 5.
*/
suspend fun connectNestsSpeaker(
httpClient: NestsClient,
@@ -177,6 +182,9 @@ suspend fun connectNestsSpeaker(
speakerPubkeyHex: String,
captureFactory: () -> AudioCapture,
encoderFactory: () -> OpusEncoder,
framesPerGroup: Int =
com.vitorpamplona.nestsclient.audio
.NestMoqLiteBroadcaster.DEFAULT_FRAMES_PER_GROUP,
): NestsSpeaker {
val state =
MutableStateFlow<NestsSpeakerState>(
@@ -240,6 +248,7 @@ suspend fun connectNestsSpeaker(
encoderFactory = encoderFactory,
scope = scope,
mutableState = state,
framesPerGroup = framesPerGroup,
)
}
nestsClient/src/commonMain/kotlin/com/vitorpamplona/nestsclient/audio/NestMoqLiteBroadcaster.kt
+67 -15
View File
@@ -41,7 +41,41 @@ class NestMoqLiteBroadcaster(
private val encoder: OpusEncoder,
private val publisher: MoqLitePublisherHandle,
private val scope: CoroutineScope,
/**
* Number of consecutive Opus frames to pack into a single moq-lite
* group (= one QUIC unidirectional stream). The first call to
* [MoqLitePublisherHandle.send] in each group opens the stream;
* subsequent calls within the same group write additional
* varint-prefixed frames; [MoqLitePublisherHandle.endGroup] FINs
* the stream and the next [send] starts a fresh group.
*
* **Default = 5 (≈ 100 ms of audio per group).** This is a
* mitigation for a production loss cliff observed against
* `nostrnests.com`: at one-frame-per-group and 20 ms cadence the
* client opens 50 uni streams/second, and somewhere around the
* 99th stream the connection enters a state where new uni streams'
* data stops being delivered to the listener, even though
* `publisher.send` still returns true. Packing 5 frames per group
* reduces the stream-creation rate to 10/second, which the prod
* sweep (`NostrnestsProdAudioTransmissionTest.sweep_frames_per_group_5`)
* shows delivers 100/100 frames cleanly. See
* `nestsClient/plans/2026-05-01-quic-stream-cliff-investigation.md`.
*
* Trade-off: a brand-new subscriber that attaches mid-broadcast
* picks up at the next group boundary per moq-lite "from-latest"
* semantics. With 5 frames per group, late joiners miss up to
* 100 ms of audio. With the original 1 frame per group it was
* up to 20 ms. Both are imperceptible for live audio rooms.
*
* Set to 1 to restore the original behaviour for testing or for
* deployments to relays that don't exhibit the stream-cliff bug.
*/
private val framesPerGroup: Int = DEFAULT_FRAMES_PER_GROUP,
) {
init {
require(framesPerGroup >= 1) { "framesPerGroup must be >= 1, got $framesPerGroup" }
}
private var job: Job? = null
@Volatile private var stopped: Boolean = false
@@ -67,6 +101,12 @@ class NestMoqLiteBroadcaster(
}
job =
scope.launch {
// Counts frames written to the current moq-lite group.
// Reset to 0 immediately after each [endGroup] so the
// next [send] auto-starts a fresh group via
// [MoqLitePublisherHandle.send]'s "open on first frame"
// contract.
var framesInCurrentGroup = 0
try {
while (true) {
val pcm = capture.readFrame() ?: break
@@ -87,23 +127,17 @@ class NestMoqLiteBroadcaster(
}
if (opus.isEmpty()) continue
if (muted) continue
// One Opus frame per moq-lite group — mirrors the
// nests JS reference's audio publish path, and is
// load-bearing for the listener-survives-publisher-
// recycle invariant: a brand-new subscriber that
// attaches mid-broadcast (e.g. listener wrapper
// re-subscribing after a publisher cycle) gets the
// NEXT group's frames per moq-lite "from-latest"
// semantics. Without endGroup, the entire broadcast
// is one giant group and new subscribers wait
// indefinitely. The 20 ms cadence here means at
// most one frame of audio missed for any new
// subscriber. See
// `nestsClient/plans/2026-04-26-moq-lite-gap.md`'s
// "Group size: 1 frame per group" line.
// Pack [framesPerGroup] consecutive Opus frames
// into the same moq-lite group / QUIC uni stream
// before FINning. See the [framesPerGroup] kdoc
// for the production cliff this works around.
runCatching {
publisher.send(opus)
publisher.endGroup()
framesInCurrentGroup += 1
if (framesInCurrentGroup >= framesPerGroup) {
publisher.endGroup()
framesInCurrentGroup = 0
}
}.onFailure { t ->
if (t is CancellationException) throw t
onError(
@@ -115,6 +149,13 @@ class NestMoqLiteBroadcaster(
)
}
}
// EOF on the capture side. Flush whatever's in the
// open group so the relay sees its FIN and the
// listener doesn't sit on a half-delivered group
// buffer. Mirrors the per-group endGroup above.
if (framesInCurrentGroup > 0) {
runCatching { publisher.endGroup() }
}
} catch (ce: CancellationException) {
throw ce
} catch (t: Throwable) {
@@ -153,4 +194,15 @@ class NestMoqLiteBroadcaster(
runCatching { encoder.release() }
runCatching { publisher.close() }
}
companion object {
/**
* Default moq-lite group size = 5 Opus frames ≈ 100 ms of audio.
* Picked to keep the QUIC uni-stream creation rate under the
* production cliff observed against `nostrnests.com` while
* still giving late-joining subscribers a sub-100 ms initial
* audio gap. See [framesPerGroup] kdoc for the full rationale.
*/
const val DEFAULT_FRAMES_PER_GROUP: Int = 5
}
}