@livekit/agents 1.1.0 → 1.2.1

package/dist/stt/stt.d.cts

@@ -2,10 +2,12 @@
 import { type AudioFrame, AudioResampler } from '@livekit/rtc-node';
 import type { TypedEventEmitter as TypedEmitter } from '@livekit/typed-emitter';
 import type { ReadableStream } from 'node:stream/web';
+import type { LanguageCode } from '../language.js';
 import type { STTMetrics } from '../metrics/base.js';
 import { type APIConnectOptions } from '../types.js';
 import type { AudioBuffer } from '../utils.js';
 import { AsyncIterableQueue } from '../utils.js';
+import type { TimedString } from '../voice/index.js';
 /** Indicates start/middle/end of speech */
 export declare enum SpeechEventType {
     /**
@@ -29,18 +31,36 @@ export declare enum SpeechEventType {
      */
     END_OF_SPEECH = 3,
     /** Usage event, emitted periodically to indicate usage metrics. */
-    RECOGNITION_USAGE = 4
+    RECOGNITION_USAGE = 4,
+    /**
+     * Preflight transcript, emitted before final transcript when STT has high confidence
+     * but hasn't fully committed yet. Includes all pre-committed transcripts including
+     * final transcript from the previous STT run.
+     */
+    PREFLIGHT_TRANSCRIPT = 5
 }
 /** SpeechData contains metadata about this {@link SpeechEvent}. */
 export interface SpeechData {
-    language: string;
+    /** Language code of the speech. */
+    language: LanguageCode;
+    /** Transcribed text. */
     text: string;
+    /** Start time of the speech segment in seconds. */
     startTime: number;
+    /** End time of the speech segment in seconds. */
     endTime: number;
+    /** Confidence score of the transcription (0-1). */
     confidence: number;
+    /** Word-level timing information. */
+    words?: TimedString[];
 }
 export interface RecognitionUsage {
+    /** Duration of the audio that was recognized in seconds. */
     audioDuration: number;
+    /** Input audio tokens (for token-based STT billing). */
+    inputTokens?: number;
+    /** Output text tokens (for token-based STT billing). */
+    outputTokens?: number;
 }
 /** SpeechEvent is a packet of speech-to-text data. */
 export interface SpeechEvent {
@@ -58,6 +78,13 @@ export interface SpeechEvent {
 export interface STTCapabilities {
     streaming: boolean;
     interimResults: boolean;
+    /**
+     * Whether this STT supports aligned transcripts with word/chunk timestamps.
+     * - 'word': Provider returns word-level timestamps
+     * - 'chunk': Provider returns chunk-level timestamps (e.g., sentence/phrase boundaries)
+     * - false: Provider does not support aligned transcripts
+     */
+    alignedTranscript?: 'word' | 'chunk' | false;
 }
 export interface STTError {
     type: 'stt_error';
@@ -84,14 +111,37 @@ export declare abstract class STT extends STT_base {
     constructor(capabilities: STTCapabilities);
     /** Returns this STT's capabilities */
     get capabilities(): STTCapabilities;
+    /**
+     * Get the model name/identifier for this STT instance.
+     *
+     * @returns The model name if available, "unknown" otherwise.
+     *
+     * @remarks
+     * Plugins should override this property to provide their model information.
+     */
+    get model(): string;
+    /**
+     * Get the provider name for this STT instance.
+     *
+     * @returns The provider name if available, "unknown" otherwise.
+     *
+     * @remarks
+     * Plugins should override this property to provide their provider information.
+     */
+    get provider(): string;
     /** Receives an audio buffer and returns transcription in the form of a {@link SpeechEvent} */
-    recognize(frame: AudioBuffer): Promise<SpeechEvent>;
-    protected abstract _recognize(frame: AudioBuffer): Promise<SpeechEvent>;
+    recognize(frame: AudioBuffer, abortSignal?: AbortSignal): Promise<SpeechEvent>;
+    protected abstract _recognize(frame: AudioBuffer, abortSignal?: AbortSignal): Promise<SpeechEvent>;
     /**
      * Returns a {@link SpeechStream} that can be used to push audio frames and receive
      * transcriptions
+     *
+     * @param options - Optional configuration including connection options
      */
-    abstract stream(): SpeechStream;
+    abstract stream(options?: {
+        connOptions?: APIConnectOptions;
+    }): SpeechStream;
+    close(): Promise<void>;
 }
 /**
  * An instance of a speech-to-text stream, as an asynchronous iterable iterator.
@@ -122,12 +172,25 @@ export declare abstract class SpeechStream implements AsyncIterableIterator<Spee
     private deferredInputStream;
     private logger;
     private _connOptions;
+    private _startTimeOffset;
+    protected abortController: AbortController;
     constructor(stt: STT, sampleRate?: number, connectionOptions?: APIConnectOptions);
+    /**
+     * Runs the STT with retry logic. Errors are emitted via {@link STT} error events
+     * and then re-thrown to trigger `.finally()` cleanup.
+     *
+     * @throws {APIError} When the STT request fails with a non-retryable error
+     * @throws {APIConnectionError} When all retry attempts are exhausted
+     * @internal Not annotated with Throws<> because this is fire-and-forget via startSoon()
+     */
     private mainTask;
     private emitError;
     protected pumpInput(): Promise<void>;
     protected monitorMetrics(): Promise<void>;
     protected abstract run(): Promise<void>;
+    protected get abortSignal(): AbortSignal;
+    get startTimeOffset(): number;
+    set startTimeOffset(value: number);
     updateInputStream(audioStream: ReadableStream<AudioFrame>): void;
     detachInputStream(): void;
     /** Push an audio frame to the STT */

package/dist/stt/stt.d.ts

@@ -2,10 +2,12 @@
 import { type AudioFrame, AudioResampler } from '@livekit/rtc-node';
 import type { TypedEventEmitter as TypedEmitter } from '@livekit/typed-emitter';
 import type { ReadableStream } from 'node:stream/web';
+import type { LanguageCode } from '../language.js';
 import type { STTMetrics } from '../metrics/base.js';
 import { type APIConnectOptions } from '../types.js';
 import type { AudioBuffer } from '../utils.js';
 import { AsyncIterableQueue } from '../utils.js';
+import type { TimedString } from '../voice/index.js';
 /** Indicates start/middle/end of speech */
 export declare enum SpeechEventType {
     /**
@@ -29,18 +31,36 @@ export declare enum SpeechEventType {
      */
     END_OF_SPEECH = 3,
     /** Usage event, emitted periodically to indicate usage metrics. */
-    RECOGNITION_USAGE = 4
+    RECOGNITION_USAGE = 4,
+    /**
+     * Preflight transcript, emitted before final transcript when STT has high confidence
+     * but hasn't fully committed yet. Includes all pre-committed transcripts including
+     * final transcript from the previous STT run.
+     */
+    PREFLIGHT_TRANSCRIPT = 5
 }
 /** SpeechData contains metadata about this {@link SpeechEvent}. */
 export interface SpeechData {
-    language: string;
+    /** Language code of the speech. */
+    language: LanguageCode;
+    /** Transcribed text. */
     text: string;
+    /** Start time of the speech segment in seconds. */
     startTime: number;
+    /** End time of the speech segment in seconds. */
     endTime: number;
+    /** Confidence score of the transcription (0-1). */
     confidence: number;
+    /** Word-level timing information. */
+    words?: TimedString[];
 }
 export interface RecognitionUsage {
+    /** Duration of the audio that was recognized in seconds. */
     audioDuration: number;
+    /** Input audio tokens (for token-based STT billing). */
+    inputTokens?: number;
+    /** Output text tokens (for token-based STT billing). */
+    outputTokens?: number;
 }
 /** SpeechEvent is a packet of speech-to-text data. */
 export interface SpeechEvent {
@@ -58,6 +78,13 @@ export interface SpeechEvent {
 export interface STTCapabilities {
     streaming: boolean;
     interimResults: boolean;
+    /**
+     * Whether this STT supports aligned transcripts with word/chunk timestamps.
+     * - 'word': Provider returns word-level timestamps
+     * - 'chunk': Provider returns chunk-level timestamps (e.g., sentence/phrase boundaries)
+     * - false: Provider does not support aligned transcripts
+     */
+    alignedTranscript?: 'word' | 'chunk' | false;
 }
 export interface STTError {
     type: 'stt_error';
@@ -84,14 +111,37 @@ export declare abstract class STT extends STT_base {
     constructor(capabilities: STTCapabilities);
     /** Returns this STT's capabilities */
     get capabilities(): STTCapabilities;
+    /**
+     * Get the model name/identifier for this STT instance.
+     *
+     * @returns The model name if available, "unknown" otherwise.
+     *
+     * @remarks
+     * Plugins should override this property to provide their model information.
+     */
+    get model(): string;
+    /**
+     * Get the provider name for this STT instance.
+     *
+     * @returns The provider name if available, "unknown" otherwise.
+     *
+     * @remarks
+     * Plugins should override this property to provide their provider information.
+     */
+    get provider(): string;
     /** Receives an audio buffer and returns transcription in the form of a {@link SpeechEvent} */
-    recognize(frame: AudioBuffer): Promise<SpeechEvent>;
-    protected abstract _recognize(frame: AudioBuffer): Promise<SpeechEvent>;
+    recognize(frame: AudioBuffer, abortSignal?: AbortSignal): Promise<SpeechEvent>;
+    protected abstract _recognize(frame: AudioBuffer, abortSignal?: AbortSignal): Promise<SpeechEvent>;
     /**
      * Returns a {@link SpeechStream} that can be used to push audio frames and receive
      * transcriptions
+     *
+     * @param options - Optional configuration including connection options
      */
-    abstract stream(): SpeechStream;
+    abstract stream(options?: {
+        connOptions?: APIConnectOptions;
+    }): SpeechStream;
+    close(): Promise<void>;
 }
 /**
  * An instance of a speech-to-text stream, as an asynchronous iterable iterator.
@@ -122,12 +172,25 @@ export declare abstract class SpeechStream implements AsyncIterableIterator<Spee
     private deferredInputStream;
     private logger;
     private _connOptions;
+    private _startTimeOffset;
+    protected abortController: AbortController;
     constructor(stt: STT, sampleRate?: number, connectionOptions?: APIConnectOptions);
+    /**
+     * Runs the STT with retry logic. Errors are emitted via {@link STT} error events
+     * and then re-thrown to trigger `.finally()` cleanup.
+     *
+     * @throws {APIError} When the STT request fails with a non-retryable error
+     * @throws {APIConnectionError} When all retry attempts are exhausted
+     * @internal Not annotated with Throws<> because this is fire-and-forget via startSoon()
+     */
     private mainTask;
     private emitError;
     protected pumpInput(): Promise<void>;
     protected monitorMetrics(): Promise<void>;
     protected abstract run(): Promise<void>;
+    protected get abortSignal(): AbortSignal;
+    get startTimeOffset(): number;
+    set startTimeOffset(value: number);
     updateInputStream(audioStream: ReadableStream<AudioFrame>): void;
     detachInputStream(): void;
     /** Push an audio frame to the STT */

package/dist/stt/stt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stt.d.ts","sourceRoot":"","sources":["../../src/stt/stt.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stt.d.ts","sourceRoot":"","sources":["../../src/stt/stt.ts"],"names":[],"mappings":"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"}

package/dist/stt/stt.js

@@ -1,10 +1,10 @@
 import { AudioResampler } from "@livekit/rtc-node";
 import { EventEmitter } from "node:events";
 import { APIConnectionError, APIError } from "../_exceptions.js";
-import { calculateAudioDuration } from "../audio.js";
+import { calculateAudioDurationSeconds } from "../audio.js";
 import { log } from "../log.js";
 import { DeferredReadableStream } from "../stream/deferred_stream.js";
-import { DEFAULT_API_CONNECT_OPTIONS } from "../types.js";
+import { DEFAULT_API_CONNECT_OPTIONS, intervalForRetry } from "../types.js";
 import { AsyncIterableQueue, delay, startSoon, toError } from "../utils.js";
 var SpeechEventType = /* @__PURE__ */ ((SpeechEventType2) => {
   SpeechEventType2[SpeechEventType2["START_OF_SPEECH"] = 0] = "START_OF_SPEECH";
@@ -12,6 +12,7 @@ var SpeechEventType = /* @__PURE__ */ ((SpeechEventType2) => {
   SpeechEventType2[SpeechEventType2["FINAL_TRANSCRIPT"] = 2] = "FINAL_TRANSCRIPT";
   SpeechEventType2[SpeechEventType2["END_OF_SPEECH"] = 3] = "END_OF_SPEECH";
   SpeechEventType2[SpeechEventType2["RECOGNITION_USAGE"] = 4] = "RECOGNITION_USAGE";
+  SpeechEventType2[SpeechEventType2["PREFLIGHT_TRANSCRIPT"] = 5] = "PREFLIGHT_TRANSCRIPT";
   return SpeechEventType2;
 })(SpeechEventType || {});
 class STT extends EventEmitter {
@@ -24,22 +25,51 @@ class STT extends EventEmitter {
   get capabilities() {
     return this.#capabilities;
   }
+  /**
+   * Get the model name/identifier for this STT instance.
+   *
+   * @returns The model name if available, "unknown" otherwise.
+   *
+   * @remarks
+   * Plugins should override this property to provide their model information.
+   */
+  get model() {
+    return "unknown";
+  }
+  /**
+   * Get the provider name for this STT instance.
+   *
+   * @returns The provider name if available, "unknown" otherwise.
+   *
+   * @remarks
+   * Plugins should override this property to provide their provider information.
+   */
+  get provider() {
+    return "unknown";
+  }
   /** Receives an audio buffer and returns transcription in the form of a {@link SpeechEvent} */
-  async recognize(frame) {
+  async recognize(frame, abortSignal) {
     const startTime = process.hrtime.bigint();
-    const event = await this._recognize(frame);
-    const duration = Number((process.hrtime.bigint() - startTime) / BigInt(1e6));
+    const event = await this._recognize(frame, abortSignal);
+    const durationMs = Number((process.hrtime.bigint() - startTime) / BigInt(1e6));
     this.emit("metrics_collected", {
       type: "stt_metrics",
       requestId: event.requestId ?? "",
       timestamp: Date.now(),
-      duration,
+      durationMs,
       label: this.label,
-      audioDuration: calculateAudioDuration(frame),
-      streamed: false
+      audioDurationMs: Math.round(calculateAudioDurationSeconds(frame) * 1e3),
+      streamed: false,
+      metadata: {
+        modelProvider: this.provider,
+        modelName: this.model
+      }
     });
     return event;
   }
+  async close() {
+    return;
+  }
 }
 class SpeechStream {
   static FLUSH_SENTINEL = Symbol("FLUSH_SENTINEL");
@@ -53,6 +83,8 @@ class SpeechStream {
   deferredInputStream;
   logger = log();
   _connOptions;
+  _startTimeOffset = 0;
+  abortController = new AbortController();
   constructor(stt, sampleRate, connectionOptions = DEFAULT_API_CONNECT_OPTIONS) {
     this.#stt = stt;
     this._connOptions = connectionOptions;
@@ -60,15 +92,23 @@ class SpeechStream {
     this.neededSampleRate = sampleRate;
     this.monitorMetrics();
     this.pumpInput();
-    startSoon(() => this.mainTask().then(() => this.queue.close()));
+    startSoon(() => this.mainTask().finally(() => this.queue.close()));
   }
+  /**
+   * Runs the STT with retry logic. Errors are emitted via {@link STT} error events
+   * and then re-thrown to trigger `.finally()` cleanup.
+   *
+   * @throws {APIError} When the STT request fails with a non-retryable error
+   * @throws {APIConnectionError} When all retry attempts are exhausted
+   * @internal Not annotated with Throws<> because this is fire-and-forget via startSoon()
+   */
   async mainTask() {
     for (let i = 0; i < this._connOptions.maxRetry + 1; i++) {
       try {
         return await this.run();
       } catch (error) {
         if (error instanceof APIError) {
-          const retryInterval = this._connOptions._intervalForRetry(i);
+          const retryInterval = intervalForRetry(this._connOptions, i);
           if (this._connOptions.maxRetry === 0 || !error.retryable) {
             this.emitError({ error, recoverable: false });
             throw error;
@@ -79,10 +119,9 @@ class SpeechStream {
               options: { retryable: false }
             });
           } else {
-            this.emitError({ error, recoverable: true });
             this.logger.warn(
-              { tts: this.#stt.label, attempt: i + 1, error },
-              `failed to recognize speech, retrying in ${retryInterval}s`
+              { stt: this.#stt.label, attempt: i + 1, error },
+              `failed to recognize speech, retrying in ${retryInterval}ms`
             );
           }
           if (retryInterval > 0) {
@@ -121,20 +160,51 @@ class SpeechStream {
   }
   async monitorMetrics() {
     for await (const event of this.queue) {
-      this.output.put(event);
+      if (!this.output.closed) {
+        try {
+          this.output.put(event);
+        } catch (e) {
+          if (e instanceof Error && e.message.includes("Queue is closed")) {
+            this.logger.warn(
+              { err: e },
+              "Queue closed during transcript processing (expected during disconnect)"
+            );
+          }
+        }
+      }
       if (event.type !== 4 /* RECOGNITION_USAGE */) continue;
       const metrics = {
         type: "stt_metrics",
         timestamp: Date.now(),
         requestId: event.requestId,
-        duration: 0,
+        durationMs: 0,
         label: this.#stt.label,
-        audioDuration: event.recognitionUsage.audioDuration,
-        streamed: true
+        audioDurationMs: Math.round(event.recognitionUsage.audioDuration * 1e3),
+        inputTokens: event.recognitionUsage.inputTokens ?? 0,
+        outputTokens: event.recognitionUsage.outputTokens ?? 0,
+        streamed: true,
+        metadata: {
+          modelProvider: this.#stt.provider,
+          modelName: this.#stt.model
+        }
       };
       this.#stt.emit("metrics_collected", metrics);
     }
-    this.output.close();
+    if (!this.output.closed) {
+      this.output.close();
+    }
+  }
+  get abortSignal() {
+    return this.abortController.signal;
+  }
+  get startTimeOffset() {
+    return this._startTimeOffset;
+  }
+  set startTimeOffset(value) {
+    if (value < 0) {
+      throw new Error("startTimeOffset must be non-negative");
+    }
+    this._startTimeOffset = value;
   }
   updateInputStream(audioStream) {
     this.deferredInputStream.setSource(audioStream);
@@ -155,6 +225,10 @@ class SpeechStream {
         this.resampler = new AudioResampler(frame.sampleRate, this.neededSampleRate);
       }
     }
+    if (frame.samplesPerChannel === 0) {
+      this.input.put(frame);
+      return;
+    }
     if (this.resampler) {
       const frames = this.resampler.push(frame);
       for (const frame2 of frames) {
@@ -189,9 +263,10 @@ class SpeechStream {
   }
   /** Close both the input and output of the STT stream */
   close() {
-    this.input.close();
-    this.queue.close();
-    this.output.close();
+    if (!this.input.closed) this.input.close();
+    if (!this.queue.closed) this.queue.close();
+    if (!this.output.closed) this.output.close();
+    if (!this.abortController.signal.aborted) this.abortController.abort();
     this.closed = true;
   }
   [Symbol.asyncIterator]() {

package/dist/stt/stt.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/stt/stt.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { type AudioFrame, AudioResampler } from '@livekit/rtc-node';\nimport type { TypedEventEmitter as TypedEmitter } from '@livekit/typed-emitter';\nimport { EventEmitter } from 'node:events';\nimport type { ReadableStream } from 'node:stream/web';\nimport { APIConnectionError, APIError } from '../_exceptions.js';\nimport { calculateAudioDuration } from '../audio.js';\nimport { log } from '../log.js';\nimport type { STTMetrics } from '../metrics/base.js';\nimport { DeferredReadableStream } from '../stream/deferred_stream.js';\nimport { type APIConnectOptions, DEFAULT_API_CONNECT_OPTIONS } from '../types.js';\nimport type { AudioBuffer } from '../utils.js';\nimport { AsyncIterableQueue, delay, startSoon, toError } from '../utils.js';\n\n/** Indicates start/middle/end of speech */\nexport enum SpeechEventType {\n  /**\n   * Indicate the start of speech.\n   * If the STT doesn't support this event, this will be emitted at the same time\n   * as the first INTERIM_TRANSCRIPT.\n   */\n  START_OF_SPEECH = 0,\n  /**\n   * Interim transcript, useful for real-time transcription.\n   */\n  INTERIM_TRANSCRIPT = 1,\n  /**\n   * Final transcript, emitted when the STT is confident enough that a certain\n   * portion of the speech will not change.\n   */\n  FINAL_TRANSCRIPT = 2,\n  /**\n   * Indicate the end of speech, emitted when the user stops speaking.\n   * The first alternative is a combination of all the previous FINAL_TRANSCRIPT events.\n   */\n  END_OF_SPEECH = 3,\n  /** Usage event, emitted periodically to indicate usage metrics. */\n  RECOGNITION_USAGE = 4,\n}\n\n/** SpeechData contains metadata about this {@link SpeechEvent}. */\nexport interface SpeechData {\n  language: string;\n  text: string;\n  startTime: number;\n  endTime: number;\n  confidence: number;\n}\n\nexport interface RecognitionUsage {\n  audioDuration: number;\n}\n\n/** SpeechEvent is a packet of speech-to-text data. */\nexport interface SpeechEvent {\n  type: SpeechEventType;\n  alternatives?: [SpeechData, ...SpeechData[]];\n  requestId?: string;\n  recognitionUsage?: RecognitionUsage;\n}\n\n/**\n * Describes the capabilities of the STT provider.\n *\n * @remarks\n * At present, the framework only supports providers that have a streaming endpoint.\n */\nexport interface STTCapabilities {\n  streaming: boolean;\n  interimResults: boolean;\n}\n\nexport interface STTError {\n  type: 'stt_error';\n  timestamp: number;\n  label: string;\n  error: Error;\n  recoverable: boolean;\n}\n\nexport type STTCallbacks = {\n  ['metrics_collected']: (metrics: STTMetrics) => void;\n  ['error']: (error: STTError) => void;\n};\n\n/**\n * An instance of a speech-to-text adapter.\n *\n * @remarks\n * This class is abstract, and as such cannot be used directly. Instead, use a provider plugin that\n * exports its own child STT class, which inherits this class's methods.\n */\nexport abstract class STT extends (EventEmitter as new () => TypedEmitter<STTCallbacks>) {\n  abstract label: string;\n  #capabilities: STTCapabilities;\n\n  constructor(capabilities: STTCapabilities) {\n    super();\n    this.#capabilities = capabilities;\n  }\n\n  /** Returns this STT's capabilities */\n  get capabilities(): STTCapabilities {\n    return this.#capabilities;\n  }\n\n  /** Receives an audio buffer and returns transcription in the form of a {@link SpeechEvent} */\n  async recognize(frame: AudioBuffer): Promise<SpeechEvent> {\n    const startTime = process.hrtime.bigint();\n    const event = await this._recognize(frame);\n    const duration = Number((process.hrtime.bigint() - startTime) / BigInt(1000000));\n    this.emit('metrics_collected', {\n      type: 'stt_metrics',\n      requestId: event.requestId ?? '',\n      timestamp: Date.now(),\n      duration,\n      label: this.label,\n      audioDuration: calculateAudioDuration(frame),\n      streamed: false,\n    });\n    return event;\n  }\n  protected abstract _recognize(frame: AudioBuffer): Promise<SpeechEvent>;\n\n  /**\n   * Returns a {@link SpeechStream} that can be used to push audio frames and receive\n   * transcriptions\n   */\n  abstract stream(): SpeechStream;\n}\n\n/**\n * An instance of a speech-to-text stream, as an asynchronous iterable iterator.\n *\n * @example Looping through frames\n * ```ts\n * for await (const event of stream) {\n *   if (event.type === SpeechEventType.FINAL_TRANSCRIPT) {\n *     console.log(event.alternatives[0].text)\n *   }\n * }\n * ```\n *\n * @remarks\n * This class is abstract, and as such cannot be used directly. Instead, use a provider plugin that\n * exports its own child SpeechStream class, which inherits this class's methods.\n */\nexport abstract class SpeechStream implements AsyncIterableIterator<SpeechEvent> {\n  protected static readonly FLUSH_SENTINEL = Symbol('FLUSH_SENTINEL');\n  protected input = new AsyncIterableQueue<AudioFrame | typeof SpeechStream.FLUSH_SENTINEL>();\n  protected output = new AsyncIterableQueue<SpeechEvent>();\n  protected queue = new AsyncIterableQueue<SpeechEvent>();\n  protected neededSampleRate?: number;\n  protected resampler?: AudioResampler;\n  abstract label: string;\n  protected closed = false;\n  #stt: STT;\n  private deferredInputStream: DeferredReadableStream<AudioFrame>;\n  private logger = log();\n  private _connOptions: APIConnectOptions;\n\n  constructor(\n    stt: STT,\n    sampleRate?: number,\n    connectionOptions: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,\n  ) {\n    this.#stt = stt;\n    this._connOptions = connectionOptions;\n    this.deferredInputStream = new DeferredReadableStream<AudioFrame>();\n    this.neededSampleRate = sampleRate;\n    this.monitorMetrics();\n    this.pumpInput();\n\n    // this is a hack to immitate asyncio.create_task so that mainTask\n    // is run **after** the constructor has finished. Otherwise we get\n    // runtime error when trying to access class variables in the\n    // `run` method.\n    startSoon(() => this.mainTask().then(() => this.queue.close()));\n  }\n\n  private async mainTask() {\n    for (let i = 0; i < this._connOptions.maxRetry + 1; i++) {\n      try {\n        return await this.run();\n      } catch (error) {\n        if (error instanceof APIError) {\n          const retryInterval = this._connOptions._intervalForRetry(i);\n\n          if (this._connOptions.maxRetry === 0 || !error.retryable) {\n            this.emitError({ error, recoverable: false });\n            throw error;\n          } else if (i === this._connOptions.maxRetry) {\n            this.emitError({ error, recoverable: false });\n            throw new APIConnectionError({\n              message: `failed to recognize speech after ${this._connOptions.maxRetry + 1} attempts`,\n              options: { retryable: false },\n            });\n          } else {\n            this.emitError({ error, recoverable: true });\n            this.logger.warn(\n              { tts: this.#stt.label, attempt: i + 1, error },\n              `failed to recognize speech, retrying in ${retryInterval}s`,\n            );\n          }\n\n          if (retryInterval > 0) {\n            await delay(retryInterval);\n          }\n        } else {\n          this.emitError({ error: toError(error), recoverable: false });\n          throw error;\n        }\n      }\n    }\n  }\n\n  private emitError({ error, recoverable }: { error: Error; recoverable: boolean }) {\n    this.#stt.emit('error', {\n      type: 'stt_error',\n      timestamp: Date.now(),\n      label: this.#stt.label,\n      error,\n      recoverable,\n    });\n  }\n\n  protected async pumpInput() {\n    // TODO(AJS-35): Implement STT with webstreams API\n    const inputStream = this.deferredInputStream.stream;\n    const reader = inputStream.getReader();\n\n    try {\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) break;\n        this.pushFrame(value);\n      }\n    } catch (error) {\n      this.logger.error('Error in STTStream mainTask:', error);\n    } finally {\n      reader.releaseLock();\n    }\n  }\n\n  protected async monitorMetrics() {\n    for await (const event of this.queue) {\n      this.output.put(event);\n      if (event.type !== SpeechEventType.RECOGNITION_USAGE) continue;\n      const metrics: STTMetrics = {\n        type: 'stt_metrics',\n        timestamp: Date.now(),\n        requestId: event.requestId!,\n        duration: 0,\n        label: this.#stt.label,\n        audioDuration: event.recognitionUsage!.audioDuration,\n        streamed: true,\n      };\n      this.#stt.emit('metrics_collected', metrics);\n    }\n    this.output.close();\n  }\n\n  protected abstract run(): Promise<void>;\n\n  updateInputStream(audioStream: ReadableStream<AudioFrame>) {\n    this.deferredInputStream.setSource(audioStream);\n  }\n\n  detachInputStream() {\n    this.deferredInputStream.detachSource();\n  }\n\n  /** Push an audio frame to the STT */\n  pushFrame(frame: AudioFrame) {\n    if (this.input.closed) {\n      throw new Error('Input is closed');\n    }\n    if (this.closed) {\n      throw new Error('Stream is closed');\n    }\n\n    if (this.neededSampleRate && frame.sampleRate !== this.neededSampleRate) {\n      if (!this.resampler) {\n        this.resampler = new AudioResampler(frame.sampleRate, this.neededSampleRate);\n      }\n    }\n\n    if (this.resampler) {\n      const frames = this.resampler.push(frame);\n      for (const frame of frames) {\n        this.input.put(frame);\n      }\n    } else {\n      this.input.put(frame);\n    }\n  }\n\n  /** Flush the STT, causing it to process all pending text */\n  flush() {\n    if (this.input.closed) {\n      throw new Error('Input is closed');\n    }\n    if (this.closed) {\n      throw new Error('Stream is closed');\n    }\n    this.input.put(SpeechStream.FLUSH_SENTINEL);\n  }\n\n  /** Mark the input as ended and forbid additional pushes */\n  endInput() {\n    if (this.input.closed) {\n      throw new Error('Input is closed');\n    }\n    if (this.closed) {\n      throw new Error('Stream is closed');\n    }\n    this.input.close();\n  }\n\n  next(): Promise<IteratorResult<SpeechEvent>> {\n    return this.output.next();\n  }\n\n  /** Close both the input and output of the STT stream */\n  close() {\n    this.input.close();\n    this.queue.close();\n    this.output.close();\n    this.closed = true;\n  }\n\n  [Symbol.asyncIterator](): SpeechStream {\n    return this;\n  }\n}\n"],"mappings":"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","names":["SpeechEventType","frame"]}
+{"version":3,"sources":["../../src/stt/stt.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { type AudioFrame, AudioResampler } from '@livekit/rtc-node';\nimport type { TypedEventEmitter as TypedEmitter } from '@livekit/typed-emitter';\nimport { EventEmitter } from 'node:events';\nimport type { ReadableStream } from 'node:stream/web';\nimport { APIConnectionError, APIError } from '../_exceptions.js';\nimport { calculateAudioDurationSeconds } from '../audio.js';\nimport type { LanguageCode } from '../language.js';\nimport { log } from '../log.js';\nimport type { STTMetrics } from '../metrics/base.js';\nimport { DeferredReadableStream } from '../stream/deferred_stream.js';\nimport { type APIConnectOptions, DEFAULT_API_CONNECT_OPTIONS, intervalForRetry } from '../types.js';\nimport type { AudioBuffer } from '../utils.js';\nimport { AsyncIterableQueue, delay, startSoon, toError } from '../utils.js';\nimport type { TimedString } from '../voice/index.js';\n\n/** Indicates start/middle/end of speech */\nexport enum SpeechEventType {\n  /**\n   * Indicate the start of speech.\n   * If the STT doesn't support this event, this will be emitted at the same time\n   * as the first INTERIM_TRANSCRIPT.\n   */\n  START_OF_SPEECH = 0,\n  /**\n   * Interim transcript, useful for real-time transcription.\n   */\n  INTERIM_TRANSCRIPT = 1,\n  /**\n   * Final transcript, emitted when the STT is confident enough that a certain\n   * portion of the speech will not change.\n   */\n  FINAL_TRANSCRIPT = 2,\n  /**\n   * Indicate the end of speech, emitted when the user stops speaking.\n   * The first alternative is a combination of all the previous FINAL_TRANSCRIPT events.\n   */\n  END_OF_SPEECH = 3,\n  /** Usage event, emitted periodically to indicate usage metrics. */\n  RECOGNITION_USAGE = 4,\n  /**\n   * Preflight transcript, emitted before final transcript when STT has high confidence\n   * but hasn't fully committed yet. Includes all pre-committed transcripts including\n   * final transcript from the previous STT run.\n   */\n  PREFLIGHT_TRANSCRIPT = 5,\n}\n\n/** SpeechData contains metadata about this {@link SpeechEvent}. */\nexport interface SpeechData {\n  /** Language code of the speech. */\n  language: LanguageCode;\n  /** Transcribed text. */\n  text: string;\n  /** Start time of the speech segment in seconds. */\n  startTime: number;\n  /** End time of the speech segment in seconds. */\n  endTime: number;\n  /** Confidence score of the transcription (0-1). */\n  confidence: number;\n  /** Word-level timing information. */\n  words?: TimedString[];\n}\n\nexport interface RecognitionUsage {\n  /** Duration of the audio that was recognized in seconds. */\n  audioDuration: number;\n  /** Input audio tokens (for token-based STT billing). */\n  inputTokens?: number;\n  /** Output text tokens (for token-based STT billing). */\n  outputTokens?: number;\n}\n\n/** SpeechEvent is a packet of speech-to-text data. */\nexport interface SpeechEvent {\n  type: SpeechEventType;\n  alternatives?: [SpeechData, ...SpeechData[]];\n  requestId?: string;\n  recognitionUsage?: RecognitionUsage;\n}\n\n/**\n * Describes the capabilities of the STT provider.\n *\n * @remarks\n * At present, the framework only supports providers that have a streaming endpoint.\n */\nexport interface STTCapabilities {\n  streaming: boolean;\n  interimResults: boolean;\n  /**\n   * Whether this STT supports aligned transcripts with word/chunk timestamps.\n   * - 'word': Provider returns word-level timestamps\n   * - 'chunk': Provider returns chunk-level timestamps (e.g., sentence/phrase boundaries)\n   * - false: Provider does not support aligned transcripts\n   */\n  alignedTranscript?: 'word' | 'chunk' | false;\n}\n\nexport interface STTError {\n  type: 'stt_error';\n  timestamp: number;\n  label: string;\n  error: Error;\n  recoverable: boolean;\n}\n\nexport type STTCallbacks = {\n  ['metrics_collected']: (metrics: STTMetrics) => void;\n  ['error']: (error: STTError) => void;\n};\n\n/**\n * An instance of a speech-to-text adapter.\n *\n * @remarks\n * This class is abstract, and as such cannot be used directly. Instead, use a provider plugin that\n * exports its own child STT class, which inherits this class's methods.\n */\nexport abstract class STT extends (EventEmitter as new () => TypedEmitter<STTCallbacks>) {\n  abstract label: string;\n  #capabilities: STTCapabilities;\n\n  constructor(capabilities: STTCapabilities) {\n    super();\n    this.#capabilities = capabilities;\n  }\n\n  /** Returns this STT's capabilities */\n  get capabilities(): STTCapabilities {\n    return this.#capabilities;\n  }\n\n  /**\n   * Get the model name/identifier for this STT instance.\n   *\n   * @returns The model name if available, \"unknown\" otherwise.\n   *\n   * @remarks\n   * Plugins should override this property to provide their model information.\n   */\n  get model(): string {\n    return 'unknown';\n  }\n\n  /**\n   * Get the provider name for this STT instance.\n   *\n   * @returns The provider name if available, \"unknown\" otherwise.\n   *\n   * @remarks\n   * Plugins should override this property to provide their provider information.\n   */\n  get provider(): string {\n    return 'unknown';\n  }\n\n  /** Receives an audio buffer and returns transcription in the form of a {@link SpeechEvent} */\n  async recognize(frame: AudioBuffer, abortSignal?: AbortSignal): Promise<SpeechEvent> {\n    const startTime = process.hrtime.bigint();\n    const event = await this._recognize(frame, abortSignal);\n    const durationMs = Number((process.hrtime.bigint() - startTime) / BigInt(1000000));\n    this.emit('metrics_collected', {\n      type: 'stt_metrics',\n      requestId: event.requestId ?? '',\n      timestamp: Date.now(),\n      durationMs,\n      label: this.label,\n      audioDurationMs: Math.round(calculateAudioDurationSeconds(frame) * 1000),\n      streamed: false,\n      metadata: {\n        modelProvider: this.provider,\n        modelName: this.model,\n      },\n    });\n    return event;\n  }\n\n  protected abstract _recognize(\n    frame: AudioBuffer,\n    abortSignal?: AbortSignal,\n  ): Promise<SpeechEvent>;\n\n  /**\n   * Returns a {@link SpeechStream} that can be used to push audio frames and receive\n   * transcriptions\n   *\n   * @param options - Optional configuration including connection options\n   */\n  abstract stream(options?: { connOptions?: APIConnectOptions }): SpeechStream;\n\n  async close(): Promise<void> {\n    return;\n  }\n}\n\n/**\n * An instance of a speech-to-text stream, as an asynchronous iterable iterator.\n *\n * @example Looping through frames\n * ```ts\n * for await (const event of stream) {\n *   if (event.type === SpeechEventType.FINAL_TRANSCRIPT) {\n *     console.log(event.alternatives[0].text)\n *   }\n * }\n * ```\n *\n * @remarks\n * This class is abstract, and as such cannot be used directly. Instead, use a provider plugin that\n * exports its own child SpeechStream class, which inherits this class's methods.\n */\nexport abstract class SpeechStream implements AsyncIterableIterator<SpeechEvent> {\n  protected static readonly FLUSH_SENTINEL = Symbol('FLUSH_SENTINEL');\n  protected input = new AsyncIterableQueue<AudioFrame | typeof SpeechStream.FLUSH_SENTINEL>();\n  protected output = new AsyncIterableQueue<SpeechEvent>();\n  protected queue = new AsyncIterableQueue<SpeechEvent>();\n  protected neededSampleRate?: number;\n  protected resampler?: AudioResampler;\n  abstract label: string;\n  protected closed = false;\n  #stt: STT;\n  private deferredInputStream: DeferredReadableStream<AudioFrame>;\n  private logger = log();\n  private _connOptions: APIConnectOptions;\n  private _startTimeOffset: number = 0;\n\n  protected abortController = new AbortController();\n\n  constructor(\n    stt: STT,\n    sampleRate?: number,\n    connectionOptions: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,\n  ) {\n    this.#stt = stt;\n    this._connOptions = connectionOptions;\n    this.deferredInputStream = new DeferredReadableStream<AudioFrame>();\n    this.neededSampleRate = sampleRate;\n    this.monitorMetrics();\n    this.pumpInput();\n\n    // this is a hack to immitate asyncio.create_task so that mainTask\n    // is run **after** the constructor has finished. Otherwise we get\n    // runtime error when trying to access class variables in the\n    // `run` method.\n    startSoon(() => this.mainTask().finally(() => this.queue.close()));\n  }\n\n  /**\n   * Runs the STT with retry logic. Errors are emitted via {@link STT} error events\n   * and then re-thrown to trigger `.finally()` cleanup.\n   *\n   * @throws {APIError} When the STT request fails with a non-retryable error\n   * @throws {APIConnectionError} When all retry attempts are exhausted\n   * @internal Not annotated with Throws<> because this is fire-and-forget via startSoon()\n   */\n  private async mainTask(): Promise<void> {\n    for (let i = 0; i < this._connOptions.maxRetry + 1; i++) {\n      try {\n        return await this.run();\n      } catch (error) {\n        if (error instanceof APIError) {\n          const retryInterval = intervalForRetry(this._connOptions, i);\n\n          if (this._connOptions.maxRetry === 0 || !error.retryable) {\n            this.emitError({ error, recoverable: false });\n            throw error;\n          } else if (i === this._connOptions.maxRetry) {\n            this.emitError({ error, recoverable: false });\n            throw new APIConnectionError({\n              message: `failed to recognize speech after ${this._connOptions.maxRetry + 1} attempts`,\n              options: { retryable: false },\n            });\n          } else {\n            // Don't emit error event for recoverable errors during retry loop\n            // to avoid ERR_UNHANDLED_ERROR or premature session termination\n            this.logger.warn(\n              { stt: this.#stt.label, attempt: i + 1, error },\n              `failed to recognize speech, retrying in ${retryInterval}ms`,\n            );\n          }\n\n          if (retryInterval > 0) {\n            await delay(retryInterval);\n          }\n        } else {\n          this.emitError({ error: toError(error), recoverable: false });\n          throw error;\n        }\n      }\n    }\n  }\n\n  private emitError({ error, recoverable }: { error: Error; recoverable: boolean }) {\n    this.#stt.emit('error', {\n      type: 'stt_error',\n      timestamp: Date.now(),\n      label: this.#stt.label,\n      error,\n      recoverable,\n    });\n  }\n\n  protected async pumpInput() {\n    // TODO(AJS-35): Implement STT with webstreams API\n    const inputStream = this.deferredInputStream.stream;\n    const reader = inputStream.getReader();\n\n    try {\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) break;\n        this.pushFrame(value);\n      }\n    } catch (error) {\n      this.logger.error('Error in STTStream mainTask:', error);\n    } finally {\n      reader.releaseLock();\n    }\n  }\n\n  protected async monitorMetrics() {\n    for await (const event of this.queue) {\n      if (!this.output.closed) {\n        try {\n          this.output.put(event);\n        } catch (e) {\n          if (e instanceof Error && e.message.includes('Queue is closed')) {\n            this.logger.warn(\n              { err: e },\n              'Queue closed during transcript processing (expected during disconnect)',\n            );\n          }\n        }\n      }\n      if (event.type !== SpeechEventType.RECOGNITION_USAGE) continue;\n      const metrics: STTMetrics = {\n        type: 'stt_metrics',\n        timestamp: Date.now(),\n        requestId: event.requestId!,\n        durationMs: 0,\n        label: this.#stt.label,\n        audioDurationMs: Math.round(event.recognitionUsage!.audioDuration * 1000),\n        inputTokens: event.recognitionUsage!.inputTokens ?? 0,\n        outputTokens: event.recognitionUsage!.outputTokens ?? 0,\n        streamed: true,\n        metadata: {\n          modelProvider: this.#stt.provider,\n          modelName: this.#stt.model,\n        },\n      };\n      this.#stt.emit('metrics_collected', metrics);\n    }\n    if (!this.output.closed) {\n      this.output.close();\n    }\n  }\n\n  protected abstract run(): Promise<void>;\n\n  protected get abortSignal(): AbortSignal {\n    return this.abortController.signal;\n  }\n\n  get startTimeOffset(): number {\n    return this._startTimeOffset;\n  }\n\n  set startTimeOffset(value: number) {\n    if (value < 0) {\n      throw new Error('startTimeOffset must be non-negative');\n    }\n    this._startTimeOffset = value;\n  }\n\n  updateInputStream(audioStream: ReadableStream<AudioFrame>) {\n    this.deferredInputStream.setSource(audioStream);\n  }\n\n  detachInputStream() {\n    this.deferredInputStream.detachSource();\n  }\n\n  /** Push an audio frame to the STT */\n  pushFrame(frame: AudioFrame) {\n    if (this.input.closed) {\n      throw new Error('Input is closed');\n    }\n    if (this.closed) {\n      throw new Error('Stream is closed');\n    }\n\n    if (this.neededSampleRate && frame.sampleRate !== this.neededSampleRate) {\n      if (!this.resampler) {\n        this.resampler = new AudioResampler(frame.sampleRate, this.neededSampleRate);\n      }\n    }\n\n    if (frame.samplesPerChannel === 0) {\n      this.input.put(frame);\n      return;\n    }\n\n    if (this.resampler) {\n      const frames = this.resampler.push(frame);\n      for (const frame of frames) {\n        this.input.put(frame);\n      }\n    } else {\n      this.input.put(frame);\n    }\n  }\n\n  /** Flush the STT, causing it to process all pending text */\n  flush() {\n    if (this.input.closed) {\n      throw new Error('Input is closed');\n    }\n    if (this.closed) {\n      throw new Error('Stream is closed');\n    }\n    this.input.put(SpeechStream.FLUSH_SENTINEL);\n  }\n\n  /** Mark the input as ended and forbid additional pushes */\n  endInput() {\n    if (this.input.closed) {\n      throw new Error('Input is closed');\n    }\n    if (this.closed) {\n      throw new Error('Stream is closed');\n    }\n    this.input.close();\n  }\n\n  next(): Promise<IteratorResult<SpeechEvent>> {\n    return this.output.next();\n  }\n\n  /** Close both the input and output of the STT stream */\n  close() {\n    if (!this.input.closed) this.input.close();\n    if (!this.queue.closed) this.queue.close();\n    if (!this.output.closed) this.output.close();\n    if (!this.abortController.signal.aborted) this.abortController.abort();\n    this.closed = true;\n  }\n\n  [Symbol.asyncIterator](): SpeechStream {\n    return this;\n  }\n}\n"],"mappings":"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","names":["SpeechEventType","frame"]}

package/dist/telemetry/index.cjs

@@ -0,0 +1,72 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var telemetry_exports = {};
+__export(telemetry_exports, {
+  ExtraDetailsProcessor: () => import_logging.ExtraDetailsProcessor,
+  MetadataLogProcessor: () => import_logging.MetadataLogProcessor,
+  PinoCloudExporter: () => import_pino_otel_transport.PinoCloudExporter,
+  SimpleOTLPHttpLogExporter: () => import_otel_http_exporter.SimpleOTLPHttpLogExporter,
+  emitToOtel: () => import_pino_otel_transport.emitToOtel,
+  flushOtelLogs: () => import_traces.flushOtelLogs,
+  flushPinoLogs: () => import_pino_otel_transport.flushPinoLogs,
+  initPinoCloudExporter: () => import_pino_otel_transport.initPinoCloudExporter,
+  recordException: () => import_utils.recordException,
+  recordRealtimeMetrics: () => import_utils.recordRealtimeMetrics,
+  setTracerProvider: () => import_traces.setTracerProvider,
+  setupCloudTracer: () => import_traces.setupCloudTracer,
+  traceTypes: () => traceTypes,
+  tracer: () => import_traces.tracer,
+  uploadSessionReport: () => import_traces.uploadSessionReport
+});
+module.exports = __toCommonJS(telemetry_exports);
+var import_logging = require("./logging.cjs");
+var import_otel_http_exporter = require("./otel_http_exporter.cjs");
+var import_pino_otel_transport = require("./pino_otel_transport.cjs");
+var traceTypes = __toESM(require("./trace_types.cjs"), 1);
+var import_traces = require("./traces.cjs");
+var import_utils = require("./utils.cjs");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ExtraDetailsProcessor,
+  MetadataLogProcessor,
+  PinoCloudExporter,
+  SimpleOTLPHttpLogExporter,
+  emitToOtel,
+  flushOtelLogs,
+  flushPinoLogs,
+  initPinoCloudExporter,
+  recordException,
+  recordRealtimeMetrics,
+  setTracerProvider,
+  setupCloudTracer,
+  traceTypes,
+  tracer,
+  uploadSessionReport
+});
+//# sourceMappingURL=index.cjs.map

package/dist/telemetry/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/telemetry/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\nexport { ExtraDetailsProcessor, MetadataLogProcessor } from './logging.js';\nexport {\n  SimpleOTLPHttpLogExporter,\n  type SimpleLogRecord,\n  type SimpleOTLPHttpLogExporterConfig,\n} from './otel_http_exporter.js';\nexport {\n  emitToOtel,\n  flushPinoLogs,\n  initPinoCloudExporter,\n  PinoCloudExporter,\n  type PinoCloudExporterConfig,\n  type PinoLogObject,\n} from './pino_otel_transport.js';\nexport * as traceTypes from './trace_types.js';\nexport {\n  flushOtelLogs,\n  setTracerProvider,\n  setupCloudTracer,\n  tracer,\n  uploadSessionReport,\n  type StartSpanOptions,\n} from './traces.js';\nexport { recordException, recordRealtimeMetrics } from './utils.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAIA,qBAA4D;AAC5D,gCAIO;AACP,iCAOO;AACP,iBAA4B;AAC5B,oBAOO;AACP,mBAAuD;","names":[]}

package/dist/telemetry/index.d.cts

@@ -0,0 +1,7 @@
+export { ExtraDetailsProcessor, MetadataLogProcessor } from './logging.js';
+export { SimpleOTLPHttpLogExporter, type SimpleLogRecord, type SimpleOTLPHttpLogExporterConfig, } from './otel_http_exporter.js';
+export { emitToOtel, flushPinoLogs, initPinoCloudExporter, PinoCloudExporter, type PinoCloudExporterConfig, type PinoLogObject, } from './pino_otel_transport.js';
+export * as traceTypes from './trace_types.js';
+export { flushOtelLogs, setTracerProvider, setupCloudTracer, tracer, uploadSessionReport, type StartSpanOptions, } from './traces.js';
+export { recordException, recordRealtimeMetrics } from './utils.js';
+//# sourceMappingURL=index.d.ts.map