@mega-yfue/eufy-sdk / TalkbackHandle

Interface: TalkbackHandle

A live talkback session: audio pushed from the host to a camera's speaker, the mirror of LiveStreamHandle's inbound feed.

Audio must be in the codec the camera's speaker plays, TalkbackHandle.codec:

• aac-lc: AAC-LC, 16 kHz, mono, in ADTS frames, through write / writable(). Chunk boundaries are irrelevant; frames are recovered from the stream. With an AacEncoder, write takes 16-bit little-endian mono PCM at 16 kHz instead.
• aac-eld: one raw AAC-ELD access unit with LD-SBR (16 kHz, mono, 512 samples) per write, or per object-mode writable() write. No encoder applies.

An aac-lc stream at another rate or channel count is rejected rather than resampled. An aac-eld unit longer than the device accepts is refused with an error.

Frames are paced at their own playback rate (64 ms for aac-lc, 32 ms for aac-eld) rather than flushed as fast as they arrive, so feeding a file plays it at speed instead of overrunning the device. A live source keeps the queue near-empty and is unaffected.

Example

const talk = await cam.talkback!();
talk.on("error", (err) => console.error(err.message));
talk.on("finished", () => void talk.stop());
fs.createReadStream("greeting.aac").pipe(talk.writable());

Properties

codec

readonly codec: TalkbackCodec;

The codec this camera's speaker plays: aac-eld on a camera whose speaker plays it and whose stream on the same media session carries aac-eld, aac-lc otherwise, including when that stream carries no audio. It decides what write and writable take.

---

pending

readonly pending: number;

How many frames are still queued for the wire — 0 once everything written has reached it.

Methods

end()

end(): void;

Declare the input finished, so a drained queue can report the clip complete. writable() calls this from its final, so a piped source needs no explicit call; an imperative write caller does. Writing after this is an error, not more audio — open a new talkback for a new clip.

Returns

void

---

on()

Call Signature

on(event, listener): this;

The clip is complete: the input has ended (via end or the writable's final) AND every queued frame has reached the wire. Fires once — the natural moment to stop a finite clip.

This deliberately does NOT fire on a merely-empty queue. A realtime source keeps the queue near empty by design, so "queue is empty" arrives after the very first frame and stopping on it would cut the clip to one frame. pending is the instantaneous depth.

Parameters

event

"finished"

listener

() => void

Returns

this

Call Signature

on(event, listener): this;

The path closed — either stop was called, or the media session it rides inside ended and took it with it. It always fires exactly once, so it is a teardown hook rather than a signal that something went wrong.

Parameters

event

"stop"

listener

() => void

Returns

this

Call Signature

on(event, listener): this;

A frame the device would not play (wrong sample rate or channel count, or over its length limit), an encoder failure, or an audio frame the device never acknowledged — the channel is ordered, so an unacknowledged frame can stall playback behind it. Non-fatal: the session stays open.

Parameters

event

"error"

listener

(err) => void

Returns

this

Call Signature

on(event, listener): this;

Battery cameras only: the media session talkback rides inside has reached its power budget and will auto-stop after the notice's grace period, taking the audio with it. Call extend() to keep talking. Without a listener the session stops on schedule, which protects the battery.

Parameters

event

"budget"

listener

(notice) => void

Returns

this

---

stop()

stop(): Promise<void>;

Close the path, dropping anything still queued. Idempotent.

Returns

Promise<void>

---

writable()

writable(): Writable;

A node:stream Writable over write, for piping a file or an encoder's stdout. Applies backpressure while the pacing queue is full, so a fast source cannot outrun playback.

Returns

Writable

---

write()

write(chunk): void;

Queue audio: ADTS frames or PCM for aac-lc, one access unit per call for aac-eld. Partial ADTS frames are held.

Parameters

chunk

Buffer

Returns

void