@dtelecom/server-sdk-node 0.2.4 → 0.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -89,6 +89,16 @@ room.on('trackSubscribed', async (remoteTrack) => {
89
89
  });
90
90
  ```
91
91
 
92
+ `AudioStream` preserves silence across Opus DTX and lost-packet timestamp gaps.
93
+ After the first decoded packet, a stalled sender produces zero PCM with a 60 ms
94
+ jitter grace period, allowing downstream VAD/turn detection to observe elapsed
95
+ silence. Normal packets are emitted immediately. Silence already generated by
96
+ the timer is not inserted again when the next RTP packet arrives; accepted
97
+ resumed speech is preserved in full. Close the stream (or stop the remote track)
98
+ to stop its timer. The close log reports `timestamp_silence_ms` and
99
+ `stalled_silence_ms` for diagnosis. These counts include intentional sender
100
+ silence suppression and are not packet-loss measurements.
101
+
92
102
  ### Data Channels
93
103
 
94
104
  ```typescript
package/dist/index.d.ts CHANGED
@@ -529,6 +529,7 @@ declare class AudioSource {
529
529
  private bufferOffset;
530
530
  private readonly frameSize;
531
531
  private _onEncodedFrame;
532
+ private _onReady;
532
533
  /**
533
534
  * @param sampleRate Input sample rate (e.g. 16000 for STT/TTS)
534
535
  * @param channels Number of channels (1 = mono)
@@ -536,6 +537,13 @@ declare class AudioSource {
536
537
  constructor(sampleRate: number, channels?: number);
537
538
  /** Set the callback for encoded Opus frames. Used internally by LocalAudioTrack. */
538
539
  set onEncodedFrame(cb: ((opusData: Buffer) => void) | null);
540
+ /** True when the RTP transport is connected and frames will be sent (not dropped). */
541
+ get ready(): boolean;
542
+ /**
543
+ * Register a one-shot callback fired when the transport becomes ready.
544
+ * If already ready, the callback is invoked immediately.
545
+ */
546
+ set onReady(cb: (() => void) | null);
539
547
  /** Associate this source with a werift MediaStreamTrack */
540
548
  setTrack(track: MediaStreamTrack): void;
541
549
  /**
@@ -567,12 +575,20 @@ declare class AudioSource {
567
575
 
568
576
  declare class AudioStream implements AsyncIterable<AudioFrame> {
569
577
  private decoder;
570
- private depacketizer;
571
578
  private queue;
572
579
  private readonly outputSampleRate;
573
580
  private readonly outputChannels;
574
581
  private track;
575
582
  private _closed;
583
+ private silenceTimer;
584
+ private lastSequence;
585
+ private lastTimestamp;
586
+ private lastFrameSamples;
587
+ private lastPacketAt;
588
+ private concealedSamples;
589
+ private currentSsrc;
590
+ private timestampSilenceSamples;
591
+ private stalledSilenceSamples;
576
592
  /**
577
593
  * @param track The remote audio track to stream from
578
594
  * @param sampleRate Desired output sample rate (default: 16000 for STT)
@@ -588,6 +604,8 @@ declare class AudioStream implements AsyncIterable<AudioFrame> {
588
604
  private packetCount;
589
605
  private start;
590
606
  private processRtpPacket;
607
+ private fillStalledInput;
608
+ private emitSilence;
591
609
  private emitFrame;
592
610
  }
593
611
 
package/dist/index.js CHANGED
@@ -2038,86 +2038,6 @@ var OpusDecoder = class {
2038
2038
  }
2039
2039
  };
2040
2040
 
2041
- // src/audio/rtp-opus.ts
2042
- var log5 = createLogger("RTP-Opus");
2043
- var OPUS_PAYLOAD_TYPE = 111;
2044
- var OPUS_TIMESTAMP_INCREMENT = OPUS_FRAME_SIZE;
2045
- var OpusRtpPacketizer = class {
2046
- sequenceNumber;
2047
- timestamp;
2048
- ssrc;
2049
- payloadType;
2050
- constructor(ssrc = 0, payloadType = OPUS_PAYLOAD_TYPE) {
2051
- this.sequenceNumber = Math.floor(Math.random() * 65535);
2052
- this.timestamp = Math.floor(Math.random() * 4294967295);
2053
- this.ssrc = ssrc;
2054
- this.payloadType = payloadType;
2055
- }
2056
- /**
2057
- * Get the next RTP header values for an Opus frame.
2058
- * Call this for each 20ms frame to get incrementing seq/ts.
2059
- */
2060
- nextPacketInfo() {
2061
- const info = {
2062
- sequenceNumber: this.sequenceNumber & 65535,
2063
- timestamp: this.timestamp >>> 0,
2064
- ssrc: this.ssrc
2065
- };
2066
- this.sequenceNumber = this.sequenceNumber + 1 & 65535;
2067
- this.timestamp = this.timestamp + OPUS_TIMESTAMP_INCREMENT >>> 0;
2068
- return info;
2069
- }
2070
- /** Reset the packetizer state */
2071
- reset() {
2072
- this.sequenceNumber = Math.floor(Math.random() * 65535);
2073
- this.timestamp = Math.floor(Math.random() * 4294967295);
2074
- }
2075
- };
2076
- var OpusRtpDepacketizer = class {
2077
- lastSequenceNumber = -1;
2078
- lastTimestamp = -1;
2079
- lostPackets = 0;
2080
- /**
2081
- * Process an incoming RTP packet containing an Opus frame.
2082
- * Returns the Opus payload and metadata.
2083
- */
2084
- processPacket(payload, sequenceNumber, timestamp) {
2085
- let lost = 0;
2086
- const isFirst = this.lastSequenceNumber === -1;
2087
- if (!isFirst) {
2088
- const expectedSeq = this.lastSequenceNumber + 1 & 65535;
2089
- if (sequenceNumber !== expectedSeq) {
2090
- if (sequenceNumber > this.lastSequenceNumber) {
2091
- lost = sequenceNumber - this.lastSequenceNumber - 1;
2092
- } else {
2093
- lost = 65535 - this.lastSequenceNumber + sequenceNumber;
2094
- }
2095
- this.lostPackets += lost;
2096
- if (lost > 0) {
2097
- log5.debug(`Lost ${lost} packets (seq ${this.lastSequenceNumber} \u2192 ${sequenceNumber})`);
2098
- }
2099
- }
2100
- }
2101
- this.lastSequenceNumber = sequenceNumber;
2102
- this.lastTimestamp = timestamp;
2103
- return {
2104
- opusFrame: payload,
2105
- lost,
2106
- isFirst
2107
- };
2108
- }
2109
- /** Total packets lost since creation */
2110
- get totalLost() {
2111
- return this.lostPackets;
2112
- }
2113
- /** Reset depacketizer state */
2114
- reset() {
2115
- this.lastSequenceNumber = -1;
2116
- this.lastTimestamp = -1;
2117
- this.lostPackets = 0;
2118
- }
2119
- };
2120
-
2121
2041
  // src/audio/resampler.ts
2122
2042
  function downsample(input, fromRate, toRate, channels = 1) {
2123
2043
  if (fromRate === toRate) {
@@ -2243,15 +2163,25 @@ var AsyncQueue = class {
2243
2163
  };
2244
2164
 
2245
2165
  // src/audio/audio-stream.ts
2246
- var log6 = createLogger("AudioStream");
2166
+ var log5 = createLogger("AudioStream");
2167
+ var SILENCE_GRACE_MS = 60;
2168
+ var MAX_TIMESTAMP_GAP_SAMPLES = OPUS_SAMPLE_RATE * 3;
2247
2169
  var AudioStream = class {
2248
2170
  decoder = null;
2249
- depacketizer;
2250
2171
  queue;
2251
2172
  outputSampleRate;
2252
2173
  outputChannels;
2253
2174
  track = null;
2254
2175
  _closed = false;
2176
+ silenceTimer = null;
2177
+ lastSequence = null;
2178
+ lastTimestamp = null;
2179
+ lastFrameSamples = 0;
2180
+ lastPacketAt = 0;
2181
+ concealedSamples = 0;
2182
+ currentSsrc = null;
2183
+ timestampSilenceSamples = 0;
2184
+ stalledSilenceSamples = 0;
2255
2185
  /**
2256
2186
  * @param track The remote audio track to stream from
2257
2187
  * @param sampleRate Desired output sample rate (default: 16000 for STT)
@@ -2260,7 +2190,6 @@ var AudioStream = class {
2260
2190
  constructor(track, sampleRate = 16e3, channels = 1) {
2261
2191
  this.outputSampleRate = sampleRate;
2262
2192
  this.outputChannels = channels;
2263
- this.depacketizer = new OpusRtpDepacketizer();
2264
2193
  this.queue = new AsyncQueue();
2265
2194
  this.track = track;
2266
2195
  this.start();
@@ -2272,13 +2201,15 @@ var AudioStream = class {
2272
2201
  close() {
2273
2202
  if (this._closed) return;
2274
2203
  this._closed = true;
2204
+ if (this.silenceTimer) clearInterval(this.silenceTimer);
2205
+ this.silenceTimer = null;
2275
2206
  this.queue.close();
2276
2207
  if (this.decoder) {
2277
2208
  this.decoder.destroy();
2278
2209
  this.decoder = null;
2279
2210
  }
2280
2211
  this.track = null;
2281
- log6.debug("AudioStream closed");
2212
+ log5.info(`AudioStream closed: packets=${this.packetCount}, timestamp_silence_ms=${Math.round(this.timestampSilenceSamples / 48)}, stalled_silence_ms=${Math.round(this.stalledSilenceSamples / 48)}`);
2282
2213
  }
2283
2214
  [Symbol.asyncIterator]() {
2284
2215
  return this.queue[Symbol.asyncIterator]();
@@ -2294,19 +2225,19 @@ var AudioStream = class {
2294
2225
  this.packetCount++;
2295
2226
  if (this.firstSsrc === null) {
2296
2227
  this.firstSsrc = rtpPacket.header.ssrc;
2297
- log6.info(`AudioStream first RTP: ssrc=${this.firstSsrc}, trackUuid=${trackUuid}`);
2228
+ log5.info(`AudioStream first RTP: ssrc=${this.firstSsrc}, trackUuid=${trackUuid}`);
2298
2229
  } else if (rtpPacket.header.ssrc !== this.firstSsrc && this.packetCount < 20) {
2299
- log6.warn(`AudioStream SSRC changed: ${this.firstSsrc} \u2192 ${rtpPacket.header.ssrc}, trackUuid=${trackUuid}`);
2230
+ log5.warn(`AudioStream SSRC changed: ${this.firstSsrc} \u2192 ${rtpPacket.header.ssrc}, trackUuid=${trackUuid}`);
2300
2231
  }
2301
2232
  try {
2302
2233
  this.processRtpPacket(rtpPacket);
2303
2234
  } catch (err) {
2304
- log6.error("Failed to process RTP packet", err);
2235
+ log5.error("Failed to process RTP packet", err);
2305
2236
  }
2306
2237
  });
2307
2238
  this.track.onReceiveRtp.once(() => {
2308
2239
  });
2309
- log6.debug(`AudioStream started, output: ${this.outputSampleRate}Hz ${this.outputChannels}ch, trackUuid=${trackUuid}`);
2240
+ log5.debug(`AudioStream started, output: ${this.outputSampleRate}Hz ${this.outputChannels}ch, trackUuid=${trackUuid}`);
2310
2241
  }
2311
2242
  processRtpPacket(rtp) {
2312
2243
  if (!rtp.payload || rtp.payload.length === 0) {
@@ -2314,31 +2245,66 @@ var AudioStream = class {
2314
2245
  }
2315
2246
  const payloadCopy = Buffer.from(rtp.payload);
2316
2247
  if (payloadCopy.length > 1500) {
2317
- log6.warn(`Skipping oversized RTP payload: ${payloadCopy.length} bytes`);
2248
+ log5.warn(`Skipping oversized RTP payload: ${payloadCopy.length} bytes`);
2318
2249
  return;
2319
2250
  }
2320
- if (!this.decoder) {
2321
- this.decoder = new OpusDecoder(OPUS_SAMPLE_RATE, this.outputChannels);
2251
+ if (this.currentSsrc !== rtp.header.ssrc) {
2252
+ this.currentSsrc = rtp.header.ssrc;
2253
+ this.lastSequence = this.lastTimestamp = null;
2254
+ this.concealedSamples = 0;
2255
+ this.decoder?.destroy();
2256
+ this.decoder = null;
2322
2257
  }
2323
- const { opusFrame, lost } = this.depacketizer.processPacket(
2324
- payloadCopy,
2325
- rtp.header.sequenceNumber,
2326
- rtp.header.timestamp
2327
- );
2328
- for (let i = 0; i < lost && i < 3; i++) {
2329
- const silence = Buffer.alloc(OPUS_FRAME_SIZE * this.outputChannels * 2);
2330
- this.emitFrame(silence);
2258
+ if (this.lastSequence !== null) {
2259
+ const delta = rtp.header.sequenceNumber - this.lastSequence & 65535;
2260
+ if (delta === 0 || delta >= 32768) return;
2331
2261
  }
2332
- if (opusFrame.length < 1) {
2333
- return;
2262
+ if (!this.decoder) {
2263
+ this.decoder = new OpusDecoder(OPUS_SAMPLE_RATE, this.outputChannels);
2334
2264
  }
2335
2265
  try {
2336
- const opusCopy = Buffer.alloc(opusFrame.length);
2337
- opusFrame.copy(opusCopy);
2266
+ const opusCopy = Buffer.from(payloadCopy);
2338
2267
  const pcmBuffer = this.decoder.decode(opusCopy);
2268
+ if (this.lastTimestamp !== null) {
2269
+ const timestampDelta = rtp.header.timestamp - this.lastTimestamp | 0;
2270
+ const missing = timestampDelta - this.lastFrameSamples - this.concealedSamples;
2271
+ if (missing > 0 && missing <= MAX_TIMESTAMP_GAP_SAMPLES) {
2272
+ this.emitSilence(missing);
2273
+ this.timestampSilenceSamples += missing;
2274
+ } else if (missing > MAX_TIMESTAMP_GAP_SAMPLES || timestampDelta < 0) {
2275
+ log5.warn("Audio RTP timestamp discontinuity; rebasing receive timeline");
2276
+ }
2277
+ }
2339
2278
  this.emitFrame(pcmBuffer);
2279
+ this.lastSequence = rtp.header.sequenceNumber;
2280
+ this.lastTimestamp = rtp.header.timestamp;
2281
+ this.lastFrameSamples = pcmBuffer.length / (2 * this.outputChannels);
2282
+ this.lastPacketAt = performance.now();
2283
+ this.concealedSamples = 0;
2284
+ if (!this.silenceTimer) {
2285
+ this.silenceTimer = setInterval(() => this.fillStalledInput(), 20);
2286
+ this.silenceTimer.unref();
2287
+ }
2340
2288
  } catch (err) {
2341
- log6.error(`Opus decode failed (${opusFrame.length} bytes)`, err);
2289
+ log5.error(`Opus decode failed (${payloadCopy.length} bytes)`, err);
2290
+ }
2291
+ }
2292
+ fillStalledInput() {
2293
+ if (this._closed || this.lastTimestamp === null) return;
2294
+ const elapsedSamples = Math.floor((performance.now() - this.lastPacketAt - SILENCE_GRACE_MS) * OPUS_SAMPLE_RATE / 1e3);
2295
+ const missing = elapsedSamples - this.lastFrameSamples - this.concealedSamples;
2296
+ const samples = Math.min(OPUS_FRAME_SIZE * 5, Math.floor(missing / OPUS_FRAME_SIZE) * OPUS_FRAME_SIZE);
2297
+ if (samples > 0) {
2298
+ this.emitSilence(samples);
2299
+ this.concealedSamples += samples;
2300
+ this.stalledSilenceSamples += samples;
2301
+ }
2302
+ }
2303
+ emitSilence(samples) {
2304
+ while (samples > 0) {
2305
+ const count = Math.min(samples, OPUS_FRAME_SIZE);
2306
+ this.emitFrame(Buffer.alloc(count * this.outputChannels * 2));
2307
+ samples -= count;
2342
2308
  }
2343
2309
  }
2344
2310
  emitFrame(pcm48k) {
@@ -2356,6 +2322,42 @@ var AudioStream = class {
2356
2322
  }
2357
2323
  };
2358
2324
 
2325
+ // src/audio/rtp-opus.ts
2326
+ var log6 = createLogger("RTP-Opus");
2327
+ var OPUS_PAYLOAD_TYPE = 111;
2328
+ var OPUS_TIMESTAMP_INCREMENT = OPUS_FRAME_SIZE;
2329
+ var OpusRtpPacketizer = class {
2330
+ sequenceNumber;
2331
+ timestamp;
2332
+ ssrc;
2333
+ payloadType;
2334
+ constructor(ssrc = 0, payloadType = OPUS_PAYLOAD_TYPE) {
2335
+ this.sequenceNumber = Math.floor(Math.random() * 65535);
2336
+ this.timestamp = Math.floor(Math.random() * 4294967295);
2337
+ this.ssrc = ssrc;
2338
+ this.payloadType = payloadType;
2339
+ }
2340
+ /**
2341
+ * Get the next RTP header values for an Opus frame.
2342
+ * Call this for each 20ms frame to get incrementing seq/ts.
2343
+ */
2344
+ nextPacketInfo() {
2345
+ const info = {
2346
+ sequenceNumber: this.sequenceNumber & 65535,
2347
+ timestamp: this.timestamp >>> 0,
2348
+ ssrc: this.ssrc
2349
+ };
2350
+ this.sequenceNumber = this.sequenceNumber + 1 & 65535;
2351
+ this.timestamp = this.timestamp + OPUS_TIMESTAMP_INCREMENT >>> 0;
2352
+ return info;
2353
+ }
2354
+ /** Reset the packetizer state */
2355
+ reset() {
2356
+ this.sequenceNumber = Math.floor(Math.random() * 65535);
2357
+ this.timestamp = Math.floor(Math.random() * 4294967295);
2358
+ }
2359
+ };
2360
+
2359
2361
  // src/track.ts
2360
2362
  var log7 = createLogger("Track");
2361
2363
  var TrackPublication = class extends TypedEmitter {
@@ -3050,6 +3052,8 @@ var AudioSource = class {
3050
3052
  frameSize;
3051
3053
  // Callback set by LocalAudioTrack to receive encoded Opus frames
3052
3054
  _onEncodedFrame = null;
3055
+ // Ready callback — fired once when DTLS is connected and RTP can be sent
3056
+ _onReady = null;
3053
3057
  /**
3054
3058
  * @param sampleRate Input sample rate (e.g. 16000 for STT/TTS)
3055
3059
  * @param channels Number of channels (1 = mono)
@@ -3063,6 +3067,25 @@ var AudioSource = class {
3063
3067
  /** Set the callback for encoded Opus frames. Used internally by LocalAudioTrack. */
3064
3068
  set onEncodedFrame(cb) {
3065
3069
  this._onEncodedFrame = cb;
3070
+ if (cb && this._onReady) {
3071
+ this._onReady();
3072
+ this._onReady = null;
3073
+ }
3074
+ }
3075
+ /** True when the RTP transport is connected and frames will be sent (not dropped). */
3076
+ get ready() {
3077
+ return this._onEncodedFrame !== null;
3078
+ }
3079
+ /**
3080
+ * Register a one-shot callback fired when the transport becomes ready.
3081
+ * If already ready, the callback is invoked immediately.
3082
+ */
3083
+ set onReady(cb) {
3084
+ if (cb && this._onEncodedFrame) {
3085
+ cb();
3086
+ return;
3087
+ }
3088
+ this._onReady = cb;
3066
3089
  }
3067
3090
  /** Associate this source with a werift MediaStreamTrack */
3068
3091
  setTrack(track) {