Voice

voiceConnectionReporter(): (state: 0 | 1) => void

livekitUrlFor(transportUrl: string): string

interface VoiceConnection {
  serverId: string;
  channelId: string;
  groupId: string;
  token: string;
  url: string;
  selfMuted: boolean;
  selfDeafened: boolean;
  joinedAt: Date;
}

interface VoiceParticipant {
  userId: string;
  channelId: string;
  muted: boolean;
  deafened: boolean;
  serverMuted: boolean;
  serverDeafened: boolean;
  webcam: boolean;
  stream: boolean;
  // Deprecated. P2P was removed from the platform, so both are always false.
  p2pWebcam: boolean;
  p2pStream: boolean;
  reconnecting: boolean;
}

interface VoiceKey {
  scope: VoiceKeyScope;
  key: Buffer;      // exactly 32 bytes
  version: number;
  fromId: string;
}

type VoiceKeyScope = 'participant' | 'room';

type VoiceStateFlag = 'muted' | 'deafened' | 'webcam' | 'stream' | 'p2pWebcam' | 'p2pStream';

class VoiceMediaSession {
  static attach(options: VoiceMediaOptions): Promise<VoiceMediaSession>;
  readonly player: VoicePlayer;
  readonly identity: string;
  readonly scope: 'participant' | 'room';
  get installedIdentities(): readonly string[];
  setVoiceKey(next: VoiceKeyValue): Promise<void>;
  detach(): Promise<void>;
  // Room scope only. Every one of these throws in participant scope.
  on<K extends keyof VoiceMediaSessionEvents>(event: K, listener: (...args: VoiceMediaSessionEvents[K]) => void): this;
  off<K extends keyof VoiceMediaSessionEvents>(event: K, listener: (...args: VoiceMediaSessionEvents[K]) => void): this;
  audio(): AsyncIterable<ParticipantFrame>;
  setSubscribed(identity: string, on: boolean): Promise<void>;
}

interface VoiceMediaOptions {
  url: string;
  token: string;
  botId: string;
  serverId: string;
  voiceKey: VoiceKeyValue;
  keys: VoiceFrameKeySource;
  deafened?: boolean;
  sampleRate?: number;         // publish format, default 48000
  channels?: number;           // publish format, default 2
  receiveSampleRate?: number;  // room scope only, default 48000
  receiveChannels?: number;    // room scope only, default 1
  connectionReporter?: (state: 0 | 1) => void;
  admissionTimeoutMs?: number; // default 5000, ignored without a reporter
  debug?: boolean;
  engine?: RtcNodeModule; // test seam
}

interface VoiceMediaSessionEvents {
  audio: [stream: ParticipantAudio];
}

interface PcmFrame {
  data: Int16Array;
  sampleRate: number;
  channels: number;
  samplesPerChannel: number;
}

interface ParticipantAudio {
  identity: string;
  frames: AsyncIterable<PcmFrame>;
}

interface ParticipantFrame {
  identity: string;
  frame: PcmFrame;
}

interface VoiceKeyValue {
  key: Uint8Array;
  scope: 'participant' | 'room';
  version?: number;
}

interface VoiceFrameKeySource {
  voiceFrameKeyFor(serverIdHex: string, identity: string): Uint8Array;
}

class VoicePlayer extends EventEmitter {
  constructor(deps: VoicePlayerDeps);
  get playing(): boolean;
  play(resource: AudioResource): Promise<void>;
  stop(): void;
}

interface VoicePlayerEvents {
  start: [];
  end: [];
  error: [Error];
}

interface VoicePlayerDeps {
  source: RtcAudioSource;
  makeFrame: (
    data: Int16Array,
    sampleRate: number,
    channels: number,
    samplesPerChannel: number,
  ) => unknown;
  sampleRate: number;
  channels: number;
}

interface AudioResource {
  pcm: AsyncIterable<Int16Array>;
  sampleRate?: number;  // default 48000
  channels?: number;    // default 2
  close?(): void;
}

pcmChunks(bytes: AsyncIterable<Uint8Array>, channels?: number): AsyncIterable<Int16Array>

pcmFrameBytes(frame: PcmFrame): Uint8Array

ffmpegResource(input: string, opts?: FfmpegResourceOptions): AudioResource

interface FfmpegResourceOptions {
  ffmpegPath?: string;
  sampleRate?: number;
  channels?: number;
  internals?: { spawn?: DecoderSpawn };  // test seam, not version-stable
}

ytdlpResource(url: string, opts?: YtdlpResourceOptions): Promise<AudioResource>

interface YtdlpResourceOptions extends FfmpegResourceOptions {
  ytdlpPath?: string;
  format?: string;      // default 'bestaudio*/best'
  ytdlpArgs?: string[];
  internals?: { spawn?: DecoderSpawn; run?: ExtractorRun };
}

resolveMediaUrl(url: string, opts?: YtdlpResourceOptions): Promise<string>

type DecoderSpawn = (exe: string, args: string[]) => DecoderChild;
type ExtractorRun = (
  exe: string,
  args: string[],
) => Promise<{ code: number | null; stdout: string; stderr: string }>;

probeVoiceRuntime(): Promise<VoiceRuntimeProbe>

interface VoiceRuntimeProbe {
  available: boolean;
  version?: string;
  error?: string;
  remedy?: string;
}

voiceEnvError(cause: unknown): CloakEnvironmentError

deriveParticipantVoiceKey(roomKey: Buffer, serverId: string, identity: string): Buffer

voiceKeyMaterial(key: Uint8Array): Uint8Array

voiceKeyProviderOptions(): Record<string, unknown>