@firebase/ai 2.4.0-canary.91c218db2 → 2.4.0-canary.bc5a7c4a7

package/dist/ai-public.d.ts

@@ -192,6 +192,12 @@ export declare interface AudioConversationController {
     stop: () => Promise<void>;
 }
 
+/**
+ * The audio transcription configuration.
+ */
+export declare interface AudioTranscriptionConfig {
+}
+
 /**
  * Abstract base class representing the configuration for an AI service backend.
  * This class should not be instantiated directly. Use its subclasses; {@link GoogleAIBackend} for
@@ -2020,6 +2026,24 @@ export declare interface LiveGenerationConfig {
      * The modalities of the response.
      */
     responseModalities?: ResponseModality[];
+    /**
+     * Enables transcription of audio input.
+     *
+     * When enabled, the model will respond with transcriptions of your audio input in the `inputTranscriptions` property
+     * in {@link LiveServerContent} messages. Note that the transcriptions are broken up across
+     * messages, so you may only receive small amounts of text per message. For example, if you ask the model
+     * "How are you today?", the model may transcribe that input across three messages, broken up as "How a", "re yo", "u today?".
+     */
+    inputAudioTranscription?: AudioTranscriptionConfig;
+    /**
+     * Enables transcription of audio input.
+     *
+     * When enabled, the model will respond with transcriptions of its audio output in the `outputTranscription` property
+     * in {@link LiveServerContent} messages. Note that the transcriptions are broken up across
+     * messages, so you may only receive small amounts of text per message. For example, if the model says
+     * "How are you today?", the model may transcribe that output across three messages, broken up as "How a", "re yo", "u today?".
+     */
+    outputAudioTranscription?: AudioTranscriptionConfig;
 }
 
 /**
@@ -2101,6 +2125,14 @@ export declare interface LiveServerContent {
      * model was not interrupted.
      */
     interrupted?: boolean;
+    /**
+     * Transcription of the audio that was input to the model.
+     */
+    inputTranscription?: Transcription;
+    /**
+     * Transcription of the audio output from the model.
+     */
+    outputTranscription?: Transcription;
 }
 
 /**
@@ -2163,32 +2195,65 @@ export declare class LiveSession {
      */
     send(request: string | Array<string | Part>, turnComplete?: boolean): Promise<void>;
     /**
-     * Sends realtime input to the server.
+     * Sends text to the server in realtime.
      *
-     * @param mediaChunks - The media chunks to send.
+     * @example
+     * ```javascript
+     * liveSession.sendTextRealtime("Hello, how are you?");
+     * ```
+     *
+     * @param text - The text data to send.
      * @throws If this session has been closed.
      *
      * @beta
      */
-    sendMediaChunks(mediaChunks: GenerativeContentBlob[]): Promise<void>;
+    sendTextRealtime(text: string): Promise<void>;
     /**
-     * Sends function responses to the server.
+     * Sends audio data to the server in realtime.
      *
-     * @param functionResponses - The function responses to send.
+     * @remarks The server requires that the audio data is base64-encoded 16-bit PCM at 16kHz
+     * little-endian.
+     *
+     * @example
+     * ```javascript
+     * // const pcmData = ... base64-encoded 16-bit PCM at 16kHz little-endian.
+     * const blob = { mimeType: "audio/pcm", data: pcmData };
+     * liveSession.sendAudioRealtime(blob);
+     * ```
+     *
+     * @param blob - The base64-encoded PCM data to send to the server in realtime.
      * @throws If this session has been closed.
      *
      * @beta
      */
-    sendFunctionResponses(functionResponses: FunctionResponse[]): Promise<void>;
+    sendAudioRealtime(blob: GenerativeContentBlob): Promise<void>;
     /**
-     * Sends a stream of {@link GenerativeContentBlob}.
+     * Sends video data to the server in realtime.
      *
-     * @param mediaChunkStream - The stream of {@link GenerativeContentBlob} to send.
+     * @remarks The server requires that the video is sent as individual video frames at 1 FPS. It
+     * is recommended to set `mimeType` to `image/jpeg`.
+     *
+     * @example
+     * ```javascript
+     * // const videoFrame = ... base64-encoded JPEG data
+     * const blob = { mimeType: "image/jpeg", data: videoFrame };
+     * liveSession.sendVideoRealtime(blob);
+     * ```
+     * @param blob - The base64-encoded video data to send to the server in realtime.
      * @throws If this session has been closed.
      *
      * @beta
      */
-    sendMediaStream(mediaChunkStream: ReadableStream<GenerativeContentBlob>): Promise<void>;
+    sendVideoRealtime(blob: GenerativeContentBlob): Promise<void>;
+    /**
+     * Sends function responses to the server.
+     *
+     * @param functionResponses - The function responses to send.
+     * @throws If this session has been closed.
+     *
+     * @beta
+     */
+    sendFunctionResponses(functionResponses: FunctionResponse[]): Promise<void>;
     /**
      * Yields messages received from the server.
      * This can only be used by one consumer at a time.
@@ -2206,6 +2271,28 @@ export declare class LiveSession {
      * @beta
      */
     close(): Promise<void>;
+    /**
+     * Sends realtime input to the server.
+     *
+     * @deprecated Use `sendTextRealtime()`, `sendAudioRealtime()`, and `sendVideoRealtime()` instead.
+     *
+     * @param mediaChunks - The media chunks to send.
+     * @throws If this session has been closed.
+     *
+     * @beta
+     */
+    sendMediaChunks(mediaChunks: GenerativeContentBlob[]): Promise<void>;
+    /**
+     * @deprecated Use `sendTextRealtime()`, `sendAudioRealtime()`, and `sendVideoRealtime()` instead.
+     *
+     * Sends a stream of {@link GenerativeContentBlob}.
+     *
+     * @param mediaChunkStream - The stream of {@link GenerativeContentBlob} to send.
+     * @throws If this session has been closed.
+     *
+     * @beta
+     */
+    sendMediaStream(mediaChunkStream: ReadableStream<GenerativeContentBlob>): Promise<void>;
 }
 
 /**
@@ -2897,6 +2984,20 @@ export declare interface ToolConfig {
     functionCallingConfig?: FunctionCallingConfig;
 }
 
+/**
+ * Transcription of audio. This can be returned from a {@link LiveGenerativeModel} if transcription
+ * is enabled with the `inputAudioTranscription` or `outputAudioTranscription` properties on
+ * the {@link LiveGenerationConfig}.
+ *
+ * @beta
+ */
+export declare interface Transcription {
+    /**
+     * The text transcription of the audio.
+     */
+    text?: string;
+}
+
 /**
  * A type that includes all specific Schema types.
  * @public

package/dist/ai.d.ts

@@ -232,6 +232,12 @@ export declare interface AudioConversationController {
     stop: () => Promise<void>;
 }
 
+/**
+ * The audio transcription configuration.
+ */
+export declare interface AudioTranscriptionConfig {
+}
+
 /**
  * Abstract base class representing the configuration for an AI service backend.
  * This class should not be instantiated directly. Use its subclasses; {@link GoogleAIBackend} for
@@ -2135,6 +2141,24 @@ export declare interface LiveGenerationConfig {
      * The modalities of the response.
      */
     responseModalities?: ResponseModality[];
+    /**
+     * Enables transcription of audio input.
+     *
+     * When enabled, the model will respond with transcriptions of your audio input in the `inputTranscriptions` property
+     * in {@link LiveServerContent} messages. Note that the transcriptions are broken up across
+     * messages, so you may only receive small amounts of text per message. For example, if you ask the model
+     * "How are you today?", the model may transcribe that input across three messages, broken up as "How a", "re yo", "u today?".
+     */
+    inputAudioTranscription?: AudioTranscriptionConfig;
+    /**
+     * Enables transcription of audio input.
+     *
+     * When enabled, the model will respond with transcriptions of its audio output in the `outputTranscription` property
+     * in {@link LiveServerContent} messages. Note that the transcriptions are broken up across
+     * messages, so you may only receive small amounts of text per message. For example, if the model says
+     * "How are you today?", the model may transcribe that output across three messages, broken up as "How a", "re yo", "u today?".
+     */
+    outputAudioTranscription?: AudioTranscriptionConfig;
 }
 
 /**
@@ -2226,6 +2250,14 @@ export declare interface LiveServerContent {
      * model was not interrupted.
      */
     interrupted?: boolean;
+    /**
+     * Transcription of the audio that was input to the model.
+     */
+    inputTranscription?: Transcription;
+    /**
+     * Transcription of the audio output from the model.
+     */
+    outputTranscription?: Transcription;
 }
 
 /**
@@ -2291,32 +2323,65 @@ export declare class LiveSession {
      */
     send(request: string | Array<string | Part>, turnComplete?: boolean): Promise<void>;
     /**
-     * Sends realtime input to the server.
+     * Sends text to the server in realtime.
      *
-     * @param mediaChunks - The media chunks to send.
+     * @example
+     * ```javascript
+     * liveSession.sendTextRealtime("Hello, how are you?");
+     * ```
+     *
+     * @param text - The text data to send.
      * @throws If this session has been closed.
      *
      * @beta
      */
-    sendMediaChunks(mediaChunks: GenerativeContentBlob[]): Promise<void>;
+    sendTextRealtime(text: string): Promise<void>;
     /**
-     * Sends function responses to the server.
+     * Sends audio data to the server in realtime.
      *
-     * @param functionResponses - The function responses to send.
+     * @remarks The server requires that the audio data is base64-encoded 16-bit PCM at 16kHz
+     * little-endian.
+     *
+     * @example
+     * ```javascript
+     * // const pcmData = ... base64-encoded 16-bit PCM at 16kHz little-endian.
+     * const blob = { mimeType: "audio/pcm", data: pcmData };
+     * liveSession.sendAudioRealtime(blob);
+     * ```
+     *
+     * @param blob - The base64-encoded PCM data to send to the server in realtime.
      * @throws If this session has been closed.
      *
      * @beta
      */
-    sendFunctionResponses(functionResponses: FunctionResponse[]): Promise<void>;
+    sendAudioRealtime(blob: GenerativeContentBlob): Promise<void>;
     /**
-     * Sends a stream of {@link GenerativeContentBlob}.
+     * Sends video data to the server in realtime.
      *
-     * @param mediaChunkStream - The stream of {@link GenerativeContentBlob} to send.
+     * @remarks The server requires that the video is sent as individual video frames at 1 FPS. It
+     * is recommended to set `mimeType` to `image/jpeg`.
+     *
+     * @example
+     * ```javascript
+     * // const videoFrame = ... base64-encoded JPEG data
+     * const blob = { mimeType: "image/jpeg", data: videoFrame };
+     * liveSession.sendVideoRealtime(blob);
+     * ```
+     * @param blob - The base64-encoded video data to send to the server in realtime.
      * @throws If this session has been closed.
      *
      * @beta
      */
-    sendMediaStream(mediaChunkStream: ReadableStream<GenerativeContentBlob>): Promise<void>;
+    sendVideoRealtime(blob: GenerativeContentBlob): Promise<void>;
+    /**
+     * Sends function responses to the server.
+     *
+     * @param functionResponses - The function responses to send.
+     * @throws If this session has been closed.
+     *
+     * @beta
+     */
+    sendFunctionResponses(functionResponses: FunctionResponse[]): Promise<void>;
     /**
      * Yields messages received from the server.
      * This can only be used by one consumer at a time.
@@ -2334,6 +2399,28 @@ export declare class LiveSession {
      * @beta
      */
     close(): Promise<void>;
+    /**
+     * Sends realtime input to the server.
+     *
+     * @deprecated Use `sendTextRealtime()`, `sendAudioRealtime()`, and `sendVideoRealtime()` instead.
+     *
+     * @param mediaChunks - The media chunks to send.
+     * @throws If this session has been closed.
+     *
+     * @beta
+     */
+    sendMediaChunks(mediaChunks: GenerativeContentBlob[]): Promise<void>;
+    /**
+     * @deprecated Use `sendTextRealtime()`, `sendAudioRealtime()`, and `sendVideoRealtime()` instead.
+     *
+     * Sends a stream of {@link GenerativeContentBlob}.
+     *
+     * @param mediaChunkStream - The stream of {@link GenerativeContentBlob} to send.
+     * @throws If this session has been closed.
+     *
+     * @beta
+     */
+    sendMediaStream(mediaChunkStream: ReadableStream<GenerativeContentBlob>): Promise<void>;
 }
 
 /**
@@ -3039,6 +3126,20 @@ export declare interface ToolConfig {
     functionCallingConfig?: FunctionCallingConfig;
 }
 
+/**
+ * Transcription of audio. This can be returned from a {@link LiveGenerativeModel} if transcription
+ * is enabled with the `inputAudioTranscription` or `outputAudioTranscription` properties on
+ * the {@link LiveGenerationConfig}.
+ *
+ * @beta
+ */
+export declare interface Transcription {
+    /**
+     * The text transcription of the audio.
+     */
+    text?: string;
+}
+
 /**
  * A type that includes all specific Schema types.
  * @public

package/dist/esm/index.esm.js

@@ -4,7 +4,7 @@ import { FirebaseError, Deferred, getModularInstance } from '@firebase/util';
 import { Logger } from '@firebase/logger';
 
 var name = "@firebase/ai";
-var version = "2.4.0-canary.91c218db2";
+var version = "2.4.0-canary.bc5a7c4a7";
 
 /**
  * @license
@@ -2870,75 +2870,104 @@ class LiveSession {
         this.webSocketHandler.send(JSON.stringify(message));
     }
     /**
-     * Sends realtime input to the server.
+     * Sends text to the server in realtime.
      *
-     * @param mediaChunks - The media chunks to send.
+     * @example
+     * ```javascript
+     * liveSession.sendTextRealtime("Hello, how are you?");
+     * ```
+     *
+     * @param text - The text data to send.
      * @throws If this session has been closed.
      *
      * @beta
      */
-    async sendMediaChunks(mediaChunks) {
+    async sendTextRealtime(text) {
         if (this.isClosed) {
             throw new AIError(AIErrorCode.REQUEST_ERROR, 'This LiveSession has been closed and cannot be used.');
         }
-        // The backend does not support sending more than one mediaChunk in one message.
-        // Work around this limitation by sending mediaChunks in separate messages.
-        mediaChunks.forEach(mediaChunk => {
-            const message = {
-                realtimeInput: { mediaChunks: [mediaChunk] }
-            };
-            this.webSocketHandler.send(JSON.stringify(message));
-        });
+        const message = {
+            realtimeInput: {
+                text
+            }
+        };
+        this.webSocketHandler.send(JSON.stringify(message));
     }
     /**
-     * Sends function responses to the server.
+     * Sends audio data to the server in realtime.
      *
-     * @param functionResponses - The function responses to send.
+     * @remarks The server requires that the audio data is base64-encoded 16-bit PCM at 16kHz
+     * little-endian.
+     *
+     * @example
+     * ```javascript
+     * // const pcmData = ... base64-encoded 16-bit PCM at 16kHz little-endian.
+     * const blob = { mimeType: "audio/pcm", data: pcmData };
+     * liveSession.sendAudioRealtime(blob);
+     * ```
+     *
+     * @param blob - The base64-encoded PCM data to send to the server in realtime.
      * @throws If this session has been closed.
      *
      * @beta
      */
-    async sendFunctionResponses(functionResponses) {
+    async sendAudioRealtime(blob) {
         if (this.isClosed) {
             throw new AIError(AIErrorCode.REQUEST_ERROR, 'This LiveSession has been closed and cannot be used.');
         }
         const message = {
-            toolResponse: {
-                functionResponses
+            realtimeInput: {
+                audio: blob
             }
         };
         this.webSocketHandler.send(JSON.stringify(message));
     }
     /**
-     * Sends a stream of {@link GenerativeContentBlob}.
+     * Sends video data to the server in realtime.
      *
-     * @param mediaChunkStream - The stream of {@link GenerativeContentBlob} to send.
+     * @remarks The server requires that the video is sent as individual video frames at 1 FPS. It
+     * is recommended to set `mimeType` to `image/jpeg`.
+     *
+     * @example
+     * ```javascript
+     * // const videoFrame = ... base64-encoded JPEG data
+     * const blob = { mimeType: "image/jpeg", data: videoFrame };
+     * liveSession.sendVideoRealtime(blob);
+     * ```
+     * @param blob - The base64-encoded video data to send to the server in realtime.
      * @throws If this session has been closed.
      *
      * @beta
      */
-    async sendMediaStream(mediaChunkStream) {
+    async sendVideoRealtime(blob) {
         if (this.isClosed) {
             throw new AIError(AIErrorCode.REQUEST_ERROR, 'This LiveSession has been closed and cannot be used.');
         }
-        const reader = mediaChunkStream.getReader();
-        while (true) {
-            try {
-                const { done, value } = await reader.read();
-                if (done) {
-                    break;
-                }
-                else if (!value) {
-                    throw new Error('Missing chunk in reader, but reader is not done.');
-                }
-                await this.sendMediaChunks([value]);
-            }
-            catch (e) {
-                // Re-throw any errors that occur during stream consumption or sending.
-                const message = e instanceof Error ? e.message : 'Error processing media stream.';
-                throw new AIError(AIErrorCode.REQUEST_ERROR, message);
+        const message = {
+            realtimeInput: {
+                video: blob
             }
+        };
+        this.webSocketHandler.send(JSON.stringify(message));
+    }
+    /**
+     * Sends function responses to the server.
+     *
+     * @param functionResponses - The function responses to send.
+     * @throws If this session has been closed.
+     *
+     * @beta
+     */
+    async sendFunctionResponses(functionResponses) {
+        if (this.isClosed) {
+            throw new AIError(AIErrorCode.REQUEST_ERROR, 'This LiveSession has been closed and cannot be used.');
         }
+        const message = {
+            toolResponse: {
+                functionResponses
+            }
+        };
+        this.webSocketHandler.send(JSON.stringify(message));
     }
     /**
      * Yields messages received from the server.
@@ -2996,6 +3025,62 @@ class LiveSession {
             await this.webSocketHandler.close(1000, 'Client closed session.');
         }
     }
+    /**
+     * Sends realtime input to the server.
+     *
+     * @deprecated Use `sendTextRealtime()`, `sendAudioRealtime()`, and `sendVideoRealtime()` instead.
+     *
+     * @param mediaChunks - The media chunks to send.
+     * @throws If this session has been closed.
+     *
+     * @beta
+     */
+    async sendMediaChunks(mediaChunks) {
+        if (this.isClosed) {
+            throw new AIError(AIErrorCode.REQUEST_ERROR, 'This LiveSession has been closed and cannot be used.');
+        }
+        // The backend does not support sending more than one mediaChunk in one message.
+        // Work around this limitation by sending mediaChunks in separate messages.
+        mediaChunks.forEach(mediaChunk => {
+            const message = {
+                realtimeInput: { mediaChunks: [mediaChunk] }
+            };
+            this.webSocketHandler.send(JSON.stringify(message));
+        });
+    }
+    /**
+     * @deprecated Use `sendTextRealtime()`, `sendAudioRealtime()`, and `sendVideoRealtime()` instead.
+     *
+     * Sends a stream of {@link GenerativeContentBlob}.
+     *
+     * @param mediaChunkStream - The stream of {@link GenerativeContentBlob} to send.
+     * @throws If this session has been closed.
+     *
+     * @beta
+     */
+    async sendMediaStream(mediaChunkStream) {
+        if (this.isClosed) {
+            throw new AIError(AIErrorCode.REQUEST_ERROR, 'This LiveSession has been closed and cannot be used.');
+        }
+        const reader = mediaChunkStream.getReader();
+        while (true) {
+            try {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                else if (!value) {
+                    throw new Error('Missing chunk in reader, but reader is not done.');
+                }
+                await this.sendMediaChunks([value]);
+            }
+            catch (e) {
+                // Re-throw any errors that occur during stream consumption or sending.
+                const message = e instanceof Error ? e.message : 'Error processing media stream.';
+                throw new AIError(AIErrorCode.REQUEST_ERROR, message);
+            }
+        }
+    }
 }
 
 /**
@@ -3056,13 +3141,18 @@ class LiveGenerativeModel extends AIModel {
         else {
             fullModelPath = `projects/${this._apiSettings.project}/locations/${this._apiSettings.location}/${this.model}`;
         }
+        // inputAudioTranscription and outputAudioTranscription are on the generation config in the public API,
+        // but the backend expects them to be in the `setup` message.
+        const { inputAudioTranscription, outputAudioTranscription, ...generationConfig } = this.generationConfig;
         const setupMessage = {
             setup: {
                 model: fullModelPath,
-                generationConfig: this.generationConfig,
+                generationConfig,
                 tools: this.tools,
                 toolConfig: this.toolConfig,
-                systemInstruction: this.systemInstruction
+                systemInstruction: this.systemInstruction,
+                inputAudioTranscription,
+                outputAudioTranscription
             }
         };
         try {
@@ -3768,7 +3858,7 @@ class AudioConversationRunner {
                 mimeType: 'audio/pcm',
                 data: base64
             };
-            void this.liveSession.sendMediaChunks([chunk]);
+            void this.liveSession.sendAudioRealtime(chunk);
         };
     }
     /**