Merge pull request #1 from google-gemini/thor/add-command-line-examples

feat: Add command-line examples.

Author: thorwebdev

.gitignore

@@ -0,0 +1,4 @@
+node_modules
+__pycache__
+.venv
+.env

README.md

@@ -60,6 +60,11 @@ Live API:
 
 *   **[Gen AI SDK Python example](./gemini-live-genai-python-sdk/README.md)**: Recommended for ease of use. Connect to the Gemini Live API using the Gen AI SDK to build a real-time multimodal application with a Python backend.
 *   **[Epheremal tokens and raw WebSocket example](./gemini-live-ephemeral-tokens-websocket/README.md)**: RAW protocol control. Connect to the Gemini Live API using WebSockets to build a real-time multimodal application with a JavaScript frontend and a Python backend.
+*   **[Command-line Python example](./command-line/python/README.md)**: A minimal command-line app that streams microphone audio to the Gemini Live API and plays back the response in real time using Python.
+*   **[Command-line Node.js example](./command-line/node/README.md)**: A minimal command-line app that streams microphone audio to the Gemini Live API and plays back the response in real time using Node.js.
+
+> [!TIP]
+> Install the [Gemini Live API Dev](https://github.com/google-gemini/gemini-skills?tab=readme-ov-file#gemini-live-api-dev) skill for AI-assisted development with the Live API in your coding agents.
 
 ## Partner integrations
 

command-line/node/README.md

@@ -0,0 +1,28 @@
+# Gemini Live API – Command Line (Node.js)
+
+A minimal command-line app that streams microphone audio to the Gemini Live API and plays back the response in real time. This example is intended for local testing only, not for production use cases.
+
+> **Note:** Use headphones. This script uses the system default audio input and output, which often won't include echo cancellation. To prevent the model from interrupting itself, use headphones.
+
+## Prerequisites
+
+- Node.js 20+
+- A Gemini API key ([get one here](https://aistudio.google.com/apikey))
+- SoX (`brew install sox` on macOS) — required by the `mic` package
+
+## Setup
+
+Install helpers for audio streaming. Additional system-level dependencies might be required (`sox` for Mac/Windows or ALSA for Linux). Refer to the [speaker](https://www.npmjs.com/package/speaker) and [mic](https://www.npmjs.com/package/mic) docs for detailed installation steps.
+
+```bash
+npm install @google/genai mic speaker
+```
+
+## Run
+
+```bash
+export GEMINI_API_KEY="your-api-key"
+npx tsx main.mts
+```
+
+You should see **"Connected to Gemini Live API"** and **"Microphone started. Speak now..."** — talk into your mic and Gemini will respond with audio. Press `Ctrl+C` to quit.

command-line/node/main.mts

@@ -0,0 +1,125 @@
+import { GoogleGenAI, Modality, type LiveServerMessage } from '@google/genai';
+import mic from 'mic';
+import Speaker from 'speaker';
+
+const ai = new GoogleGenAI({});
+// WARNING: Do not use API keys in client-side (browser based) applications
+// Consider using Ephemeral Tokens instead
+// More information at: https://ai.google.dev/gemini-api/docs/ephemeral-tokens
+
+// --- Live API config ---
+const model = 'gemini-2.5-flash-native-audio-preview-12-2025';
+const config = {
+  responseModalities: [Modality.AUDIO],
+  systemInstruction: "You are a helpful and friendly AI assistant.",
+};
+
+async function live() {
+  const responseQueue: LiveServerMessage[] = [];
+  const audioQueue: Buffer[] = [];
+  let speaker: Speaker | null = null;
+
+  async function waitMessage(): Promise<LiveServerMessage> {
+    while (responseQueue.length === 0) {
+      await new Promise<void>((resolve) => setImmediate(resolve));
+    }
+    return responseQueue.shift()!;
+  }
+
+  function createSpeaker() {
+    if (speaker) {
+      process.stdin.unpipe(speaker);
+      speaker.end();
+    }
+    speaker = new Speaker({
+      channels: 1,
+      bitDepth: 16,
+      sampleRate: 24000,
+    });
+    speaker.on('error', (err: Error) => console.error('Speaker error:', err));
+    process.stdin.pipe(speaker);
+  }
+
+  async function messageLoop() {
+    // Puts incoming messages in the audio queue.
+    while (true) {
+      const message = await waitMessage();
+      if (message.serverContent && message.serverContent.interrupted) {
+        // Empty the queue on interruption to stop playback
+        audioQueue.length = 0;
+        continue;
+      }
+      if (message.serverContent && message.serverContent.modelTurn && message.serverContent.modelTurn.parts) {
+        for (const part of message.serverContent.modelTurn.parts) {
+          if (part.inlineData && part.inlineData.data) {
+            audioQueue.push(Buffer.from(part.inlineData.data, 'base64'));
+          }
+        }
+      }
+    }
+  }
+
+  async function playbackLoop() {
+    // Plays audio from the audio queue.
+    while (true) {
+      if (audioQueue.length === 0) {
+        if (speaker) {
+          // Destroy speaker if no more audio to avoid warnings from speaker library
+          process.stdin.unpipe(speaker);
+          speaker.end();
+          speaker = null;
+        }
+        await new Promise<void>((resolve) => setImmediate(resolve));
+      } else {
+        if (!speaker) createSpeaker();
+        const chunk = audioQueue.shift()!;
+        await new Promise<void>((resolve) => {
+          speaker!.write(chunk, () => resolve());
+        });
+      }
+    }
+  }
+
+  // Start loops
+  messageLoop();
+  playbackLoop();
+
+  // Connect to Gemini Live API
+  const session = await ai.live.connect({
+    model: model,
+    config: config,
+    callbacks: {
+      onopen: () => console.log('Connected to Gemini Live API'),
+      onmessage: (message: LiveServerMessage) => responseQueue.push(message),
+      onerror: (e: ErrorEvent) => console.error('Error:', e.message),
+      onclose: (e: CloseEvent) => console.log('Closed:', e.reason),
+    },
+  });
+
+  // Setup Microphone for input
+  const micInstance = mic({
+    rate: '16000',
+    bitwidth: '16',
+    channels: '1',
+  });
+  const micInputStream = micInstance.getAudioStream();
+
+  micInputStream.on('data', (data: Buffer) => {
+    // API expects base64 encoded PCM data
+    session.sendRealtimeInput({
+      audio: {
+        data: data.toString('base64'),
+        mimeType: "audio/pcm;rate=16000"
+      }
+    });
+  });
+
+  micInputStream.on('error', (err: Error) => {
+    console.error('Microphone error:', err);
+  });
+
+  micInstance.start();
+  console.log('Microphone started. Speak now...');
+}
+
+live().catch(console.error);

command-line/node/mic.d.ts

@@ -0,0 +1,26 @@
+declare module 'mic' {
+  import { Transform } from 'stream';
+
+  interface MicOptions {
+    rate?: string;
+    bitwidth?: string;
+    channels?: string;
+    encoding?: string;
+    endian?: string;
+    device?: string;
+    exitOnSilence?: number;
+    fileType?: string;
+    debug?: boolean;
+  }
+
+  interface MicInstance {
+    start(): void;
+    stop(): void;
+    pause(): void;
+    resume(): void;
+    getAudioStream(): Transform;
+  }
+
+  function mic(options?: MicOptions): MicInstance;
+  export = mic;
+}