@signalwire/js 4.0.0-dev-20260421201955 → 4.0.0-dev-20260422003445

package/dist/index.d.cts

@@ -1742,11 +1742,31 @@ declare class Participant extends Destroyable implements CallParticipant {
   get videoMuted$(): Observable<boolean | undefined>;
   /** Observable indicating whether the participant is deafened. */
   get deaf$(): Observable<boolean | undefined>;
-  /** Observable of the participant's microphone input volume. */
+  /**
+   * Observable of the participant's **server-side** microphone input volume
+   * as reported by the mix engine. This is gain applied on the bridged audio
+   * leg (FreeSWITCH channel read volume), NOT the local browser mic. For a
+   * local PC mic control, see {@link Call.setLocalMicrophoneGain}.
+   *
+   * @see {@link setAudioInputVolume}
+   */
   get inputVolume$(): Observable<number | undefined>;
-  /** Observable of the participant's speaker output volume. */
+  /**
+   * Observable of the participant's **server-side** speaker output volume as
+   * reported by the mix engine (FreeSWITCH channel write volume). NOT the
+   * local HTML `<audio>` element volume — set that on your own element.
+   *
+   * @see {@link setAudioOutputVolume}
+   */
   get outputVolume$(): Observable<number | undefined>;
-  /** Observable of the microphone input sensitivity level. */
+  /**
+   * Observable of the **conference-only** microphone energy/gate sensitivity
+   * level for this member. Routes through the conferencing mix engine and has
+   * no effect on 1:1 WebRTC calls. Populated from `member.updated` events for
+   * conference members.
+   *
+   * @see {@link setAudioInputSensitivity}
+   */
   get inputSensitivity$(): Observable<number | undefined>;
   /** Observable indicating whether echo cancellation is enabled. */
   get echoCancellation$(): Observable<boolean | undefined>;
@@ -1790,11 +1810,21 @@ declare class Participant extends Destroyable implements CallParticipant {
   get videoMuted(): boolean;
   /** Whether the participant is deafened (incoming audio muted). */
   get deaf(): boolean;
-  /** Current microphone input volume level, or `undefined` if not set. */
+  /**
+   * Current **server-side** microphone input volume as reported by the mix
+   * engine, or `undefined` if not set. Not the local PC mic — see
+   * {@link Call.setLocalMicrophoneGain} for browser-side control.
+   */
   get inputVolume(): number | undefined;
-  /** Current speaker output volume level, or `undefined` if not set. */
+  /**
+   * Current **server-side** speaker output volume from the mix engine, or
+   * `undefined` if not set. Not the local `<audio>` element volume.
+   */
   get outputVolume(): number | undefined;
-  /** Current microphone input sensitivity level, or `undefined` if not set. */
+  /**
+   * Current **conference-only** microphone sensitivity/gate level, or
+   * `undefined` if not set. Applies only to conference members.
+   */
   get inputSensitivity(): number | undefined;
   /** Whether echo cancellation is enabled. */
   get echoCancellation(): boolean;
@@ -1839,15 +1869,40 @@ declare class Participant extends Destroyable implements CallParticipant {
   /** Toggles noise suppression on the audio input. */
   toggleNoiseSuppression(): Promise<void>;
   toggleLowbitrate(): Promise<void>;
-  /** Sets the microphone input sensitivity level. */
+  /**
+   * Adjusts the **conference-only** microphone energy gate / sensitivity level
+   * for this member. Routes through the conferencing mix engine
+   * (`signalwire.conferencing member.set_input_sensitivity`) and has no effect
+   * on 1:1 WebRTC calls — for those, use browser audio constraints via
+   * {@link Call.setNoiseSuppression} / {@link Call.setAutoGainControl}.
+   *
+   * This is **not** a local PC mic gain control; it only changes how the
+   * server-side mixer decides to open the mic gate on this participant.
+   *
+   * @param value - Sensitivity level as understood by the conference engine
+   *   (integer, larger values are more sensitive).
+   */
   setAudioInputSensitivity(value: number): Promise<void>;
   /**
-   * Sets the microphone input volume level.
+   * Sets the **server-side** microphone volume on this participant's bridged
+   * call leg. Applies a multiplier to the audio flowing through the mix
+   * engine (FreeSWITCH channel read volume) — changes what other participants
+   * hear, not what the local browser captures.
+   *
+   * For local PC mic gain, use {@link Call.setLocalMicrophoneGain} instead.
+   *
    * @param value - Volume level (0-100).
    */
   setAudioInputVolume(value: number): Promise<void>;
   /**
-   * Sets the speaker output volume level.
+   * Sets the **server-side** speaker volume on this participant's bridged call
+   * leg (FreeSWITCH channel write volume) — what this participant hears from
+   * the mix before it reaches their client.
+   *
+   * For local playback volume (the `<audio>` element the consumer attaches
+   * `remoteStream` to), set `audioElement.volume` directly in the consumer's
+   * code.
+   *
    * @param value - Volume level (0-100).
    */
   setAudioOutputVolume(value: number): Promise<void>;
@@ -3586,6 +3641,21 @@ declare class SignalWire extends Destroyable implements DeviceController {
   selectVideoInputDevice(device: MediaDeviceInfo | null): void;
   /** Sets the preferred audio output device. */
   selectAudioOutputDevice(device: MediaDeviceInfo | null): void;
+  /**
+   * Apply the currently selected audio output device to an HTMLMediaElement
+   * (e.g. the `<audio>` or `<video>` element the consumer attached the
+   * remote stream to). Uses `HTMLMediaElement.setSinkId` under the hood.
+   * Returns a `Promise<boolean>`: `true` if the sink was applied,
+   * `false` if the browser doesn't support `setSinkId` or no device is
+   * selected.
+   *
+   * @example
+   * ```ts
+   * audioEl.srcObject = call.remoteStream;
+   * await client.applySelectedAudioOutputDevice(audioEl);
+   * ```
+   */
+  applySelectedAudioOutputDevice(element: HTMLMediaElement): Promise<boolean>;
   /** Starts monitoring for media device changes (connect/disconnect). */
   enableDeviceMonitoring(): void;
   /** Stops monitoring for media device changes. */
@@ -3686,6 +3756,109 @@ declare class StaticCredentialProvider implements CredentialProvider {
   authenticate(): Promise<SDKCredential>;
 }
 //#endregion
+//#region src/controllers/LocalAudioPipeline.d.ts
+/**
+ * Options for {@link LocalAudioPipeline}.
+ */
+interface LocalAudioPipelineOptions {
+  /** Factory for AudioContext — override for tests. Defaults to `new AudioContext()`. */
+  audioContextFactory?: () => AudioContext;
+  /** Initial gain (0..2, where 1 is unity). Defaults to 1. */
+  initialGain?: number;
+  /** RMS level [0..1] above which speaking$ emits true. Defaults to {@link VAD_THRESHOLD}. */
+  speakingThreshold?: number;
+  /**
+   * Milliseconds of silence below the threshold before speaking$ flips back to
+   * false. Prevents flicker on normal speech gaps. Defaults to {@link VAD_HOLD_MS}.
+   */
+  speakingHoldMs?: number;
+  /** Polling interval for level$. Defaults to {@link AUDIO_LEVEL_POLL_INTERVAL_MS}. */
+  pollIntervalMs?: number;
+}
+/**
+ * Web Audio pipeline for the local microphone stream.
+ *
+ * Wraps the raw mic `MediaStreamTrack` in a graph of:
+ *
+ * ```
+ *   MediaStreamAudioSourceNode  →  GainNode  →  AnalyserNode  →  MediaStreamAudioDestinationNode
+ * ```
+ *
+ * The {@link outputTrack} from the destination node is what callers should
+ * attach to the `RTCRtpSender` in place of the raw mic track. The same
+ * destination track is reused across input changes (device switch, mute /
+ * unmute track replacement) so the sender reference stays stable — only the
+ * source end of the graph is rebuilt.
+ *
+ * The pipeline owns a single {@link AudioContext}. Callers must invoke
+ * {@link destroy} to release it when the call ends.
+ */
+declare class LocalAudioPipeline extends Destroyable {
+  private readonly _audioContext;
+  private readonly _gainNode;
+  private readonly _analyser;
+  private readonly _destination;
+  private readonly _analyserBuffer;
+  private readonly _speakingThreshold;
+  private readonly _speakingHoldMs;
+  private readonly _pollIntervalMs;
+  private _inputSource;
+  private _inputStream;
+  private _lastSpokeAt;
+  private _gain$;
+  /** 1 when audio should pass through, 0 when silenced by PTT. */
+  private _pttMultiplier;
+  constructor(options?: LocalAudioPipelineOptions);
+  /** Observable of the current gain value (0..2). */
+  get gain$(): Observable<number>;
+  /** Current gain value (0..2). */
+  get gain(): number;
+  /**
+   * Processed output track to attach to the RTCRtpSender. Stable reference
+   * across input changes, so `sender.replaceTrack(pipeline.outputTrack)` only
+   * needs to be called once.
+   */
+  get outputTrack(): MediaStreamTrack;
+  /**
+   * Root-mean-square audio level of the input signal, 0..1. Emits on a fixed
+   * interval (~30fps by default).
+   */
+  get level$(): Observable<number>;
+  /**
+   * Boolean VAD derived from {@link level$}. True while level ≥ threshold or
+   * during the hold window after the last frame that crossed the threshold.
+   */
+  get speaking$(): Observable<boolean>;
+  /**
+   * Set gain multiplier applied to the input signal. 0 = silence,
+   * 1 = unity, 2 = 2x. Values are clamped to [0, 2]. The effective gain on
+   * the graph also respects the current PTT state.
+   */
+  setGain(value: number): void;
+  /**
+   * Silence the graph when `active = false`, otherwise restore the configured
+   * gain. Use this from a PTT handler: released → `false`, held → `true`.
+   * Orthogonal to {@link setGain} — once PTT returns to active, the last
+   * configured gain reappears.
+   */
+  setPTTActive(active: boolean): void;
+  private applyEffectiveGain;
+  /**
+   * Wire a new raw mic track as the pipeline's input. Replaces any previous
+   * input source and reconnects the graph so {@link outputTrack} continues
+   * to emit the processed audio. Pass `null` to disconnect the input (the
+   * output track stays alive but emits silence).
+   *
+   * Also resumes the underlying AudioContext on attach — Chrome creates it
+   * in a suspended state and the graph won't process (the destination
+   * track emits silence) until resume() succeeds.
+   */
+  setInputTrack(track: MediaStreamTrack | null): void;
+  destroy(): void;
+  private computeLevel;
+  private evaluateSpeaking;
+}
+//#endregion
 //#region src/controllers/RTCPeerConnectionController.d.ts
 interface RTCPeerConnectionControllerOptions extends MediaOptions {
   callId?: string;
@@ -3746,6 +3919,7 @@ declare class RTCPeerConnectionController extends Destroyable {
   private _remoteDescription$;
   private _remoteStream$;
   private _remoteOfferMediaDirections;
+  private _localAudioPipeline;
   constructor(options?: RTCPeerConnectionControllerOptionsPartial, remoteSessionDescription?: string, deviceController?: DeviceController);
   private get iceGatheringController();
   private get shouldEmitLocalDescription();
@@ -3858,6 +4032,17 @@ declare class RTCPeerConnectionController extends Destroyable {
   private getDisplayMedia;
   private setupRemoteTracks;
   restoreTrackSender(kind: 'audio' | 'video' | 'both'): Promise<void>;
+  /**
+   * Return the lazily-created {@link LocalAudioPipeline}, constructing it on
+   * first access. On creation the current audio sender's track is routed
+   * through the pipeline (input → gain → analyser → destination) and the
+   * sender is switched to emit the processed track. Returns `null` when no
+   * audio sender exists yet (pre-negotiation).
+   */
+  ensureLocalAudioPipeline(): LocalAudioPipeline | null;
+  /** The active LocalAudioPipeline, or null if it hasn't been created yet. */
+  get localAudioPipeline(): LocalAudioPipeline | null;
+  private applyLocalAudioPipelineToSender;
   /**
    * Add a local media track to the peer connection.
    * @param track - The MediaStreamTrack to add
@@ -3928,6 +4113,10 @@ interface WebRTCVerto extends VertoManager {
   requestIceRestartAll?: (relayOnly?: boolean) => Promise<void>;
   /** Request keyframes on all video-receiving legs (skips send-only screen share). */
   requestKeyframeAll?: () => void;
+  /** Lazily create (or return) the local audio pipeline for the main peer connection. */
+  ensureLocalAudioPipeline(): LocalAudioPipeline | null;
+  /** Current local audio pipeline, or null if it has not been created yet. */
+  readonly localAudioPipeline: LocalAudioPipeline | null;
 }
 //#endregion
 //#region src/managers/CallEventsManager.d.ts
@@ -4075,6 +4264,8 @@ declare class WebRTCCall extends Destroyable implements CallManager {
   private _bandwidthConstrained$;
   private _mediaParamsUpdated$;
   private _customSubscriptions;
+  private _pushToTalkEnabled;
+  private _remoteAudioMeter;
   constructor(clientSession: ClientSession, options: CallOptions, initialization: CallInitialization, address?: Address | undefined);
   /** Observable stream of errors from media, signaling, and peer connection layers. */
   get errors$(): Observable<CallError>;
@@ -4402,6 +4593,79 @@ declare class WebRTCCall extends Destroyable implements CallManager {
    * @see {@link status$} to observe the transfer progress.
    */
   transfer(options: TransferOptions): Promise<void>;
+  /**
+   * Set the local microphone gain as a percentage applied before transmission.
+   *
+   *   - `0`   = silent
+   *   - `100` = unity (no change, default)
+   *   - `200` = 2× digital boost (max; expect clipping / noise amplification)
+   *
+   * Values are clamped to [0, 200]. Engages the local audio pipeline on
+   * first use (one-time cost).
+   *
+   * Note: this is a **digital** multiplier applied in a Web Audio GainNode
+   * between your mic track and the RTCRtpSender — it does not change the
+   * physical mic's hardware sensitivity. Browsers' autoGainControl can
+   * fight the setting; call {@link setAutoGainControl}(false) for
+   * predictable behaviour.
+   *
+   * @param value - Gain percentage (0..200; 100 = unity).
+   */
+  setLocalMicrophoneGain(value: number): void;
+  /** Observable of the current local microphone gain (0..200, where 100 = unity). */
+  get localMicrophoneGain$(): Observable<number>;
+  /**
+   * Observable of the RMS audio level of the local microphone, 0..1.
+   * Emits at ~30fps while a mic track is active. Engages the local audio
+   * pipeline on first subscription.
+   */
+  get localAudioLevel$(): Observable<number>;
+  /**
+   * Observable that is `true` while the local participant is speaking
+   * (RMS level above the VAD threshold, with hold time to avoid flicker).
+   */
+  get localSpeaking$(): Observable<boolean>;
+  /**
+   * Enable push-to-talk: while {@link setPushToTalkActive} has been called
+   * with `false`, the microphone gain is forced to 0; calling
+   * {@link setPushToTalkActive} with `true` restores the configured gain.
+   * Use this instead of mute/unmute for instant talk/silence transitions
+   * because it doesn't rebuild the track.
+   *
+   * This method installs the pipeline but does not attach any keyboard
+   * listener — consumers bind the key themselves and call
+   * {@link setPushToTalkActive} on keydown/keyup.
+   */
+  enablePushToTalk(): void;
+  /** Disable push-to-talk; mic gain returns to the configured value. */
+  disablePushToTalk(): void;
+  /**
+   * While push-to-talk is enabled, sets the talk state. `true` = transmitting,
+   * `false` = silent. No-op if push-to-talk has not been enabled.
+   */
+  setPushToTalkActive(active: boolean): void;
+  /**
+   * Toggle echo cancellation on the local mic at runtime. Applied via
+   * `track.applyConstraints`; browsers that don't honour runtime constraints
+   * (notably iOS Safari) fall back to re-acquiring the track with the new
+   * constraint set and plumbing the replacement through the local audio
+   * pipeline if one is active.
+   */
+  setEchoCancellation(enabled: boolean): Promise<void>;
+  /** Toggle browser noise suppression on the local mic at runtime. */
+  setNoiseSuppression(enabled: boolean): Promise<void>;
+  /** Toggle browser automatic gain control on the local mic at runtime. */
+  setAutoGainControl(enabled: boolean): Promise<void>;
+  /**
+   * Observable of the aggregate remote audio level, 0..1 RMS. The server
+   * delivers a single mixed audio stream for all remote participants — this
+   * meter reports that mix. Per-participant audio is not available client-side.
+   *
+   * Engages a shared AudioContext on first subscription (cheap — one
+   * AnalyserNode, no GainNode, no destination) so it does not affect the
+   * caller's audio element playback.
+   */
+  get remoteAudioLevel$(): Observable<number>;
   /** Destroys the call, releasing all resources and subscriptions. */
   destroy(): void;
   /**