geminisst 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Smart Tell Line
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# geminisst 🎙️
+
+**geminisst** is a revolutionary, professional-grade Node.js library for high-accuracy **Audio-to-Text** conversion. Powered by **Google's Gemini 2.5 Flash Lite**, it offers a massive **1 Million+ context window** and next-gen multimodal understanding that suns traditional STT engines.
+
+Whether it's a 3-second voice clip or a multi-hour podcast, `geminisst` processes it with lightning speed, incredible cost-efficiency, and deep reasoning capabilities.
+
+---
+
+## 🚀 Key Features
+
+*   **Gemini 2.5 Flash Lite Engine:** Optimized for the latest AI architecture, ensuring ultra-fast response times.
+*   **1M+ Context Window:** Process massive audio files (up to several hours) in a single request.
+*   **Dynamic Thinking (Reasoning):** Uses `thinkingBudget: -1` to allow the AI to reason about the audio (accents, context, noise) before transcribing.
+*   **AI Thought Summaries:** Access the AI's internal reasoning process (`thoughts`) to understand *how* it arrived at the transcript.
+*   **Locked Core Logic:** Built-in, unoverrideable system instructions ensure the AI acts as a pure transcription engine (no summaries, no opinions, 100% verbatim).
+*   **Automatic Language Detection:** Seamlessly handles Hindi, English, Hinglish, and many other languages without manual configuration.
+*   **Processing Metadata:** Real-time tracking of token usage and exact processing time in seconds.
+*   **TypeScript Native:** Full type safety and IntelliSense support for a superior developer experience.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install geminisst
+```
+
+*Note: You need a Google Gemini API Key. Get one for free at [Google AI Studio](https://aistudio.google.com/).*
+
+---
+
+## 🛠️ Quick Start
+
+### 1. Simple Transcription
+The most basic way to use `geminisst`.
+
+```javascript
+import { audioToText } from 'geminisst';
+
+const apiKey = "YOUR_GEMINI_API_KEY";
+const result = await audioToText('./meeting.mp3', apiKey);
+
+console.log("Transcript:", result.text);
+```
+
+### 2. Advanced Usage (With Thoughts & Metadata)
+Get deeper insights into the transcription process.
+
+```javascript
+import { audioToText } from 'geminisst';
+
+async function transcribeWithInsights() {
+  const result = await audioToText('./interview.wav', 'YOUR_API_KEY', {
+    prompt: "The audio is in a mix of Hindi and English. Please use Devanagari for Hindi parts.",
+    verbose: true
+  });
+
+  // Access the AI's "Internal Monologue"
+  if (result.thoughts) {
+    console.log("AI Reasoning:", result.thoughts);
+  }
+
+  // Exact spoken words
+  console.log("Transcript:", result.text);
+
+  // Performance metrics
+  console.log(`Finished in ${result.usage.processingTimeSec}s`);
+  console.log(`Total Tokens used: ${result.usage.totalTokens}`);
+}
+
+transcribeWithInsights();
+```
+
+---
+
+## 📖 API Reference
+
+### `audioToText(filePath, apiKey, options?)`
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `filePath` | `string` | Absolute or relative path to the audio file. |
+| `apiKey` | `string` | Your Google Gemini API Key. |
+| `options` | `SSTOptions` | (Optional) Advanced configuration. |
+
+### `SSTOptions`
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `prompt` | `string` | `undefined` | Style/Language guidance (e.g., "Transcribe in English letters"). |
+| `model` | `string` | `"gemini-2.5-flash-lite"` | Override default model. |
+| `verbose` | `boolean` | `false` | Log internal steps for debugging. |
+
+### `TranscriptionResult`
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `text` | `string` | The 100% accurate, verbatim transcript. |
+| `thoughts` | `string` | AI's thought summary explaining the reasoning/language detection. |
+| `model` | `string` | The specific model version used. |
+| `usage` | `object` | Stats: `inputTokens`, `outputTokens`, `totalTokens`, `processingTimeSec`. |
+
+---
+
+## 🛡️ Transcription Rules (Locked Logic)
+
+This library is hardcoded with professional transcription rules that **cannot be overridden**, ensuring reliability:
+1.  **Verbatim Content:** Captures stutters, hesitations, and repetitions exactly.
+2.  **Noise Suppression:** Automatically ignores background noise and focuses on speech.
+3.  **No Interpretation:** Forbidden from adding opinions, interpretations, or extra content.
+4.  **Style Integrity:** Maintains the natural flow and pronunciation matching of the spoken words.
+
+---
+
+## 📄 License
+
+ISC - Distributed under the ISC License. See `LICENSE` for more information.
+
+Copyright (c) 2026, **Smart Tell Line**.

package/dist/constants.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_SYSTEM_INSTRUCTION = "You are a speech-to-text AI model. Tumhara kaam sirf ye hai ki jo bhi audio mile, usko accurately text mein convert karo. Tumhe kuch bhi summarize, interpret, ya translate nahi karna hai\u2014bas spoken words ka exact transcript generate karna hai.\nRules/Instructions:\nUser-specified language:\nAgar user language specify karta hai (Hindi, English, Hinglish, etc.), to text us language ke style mein hi likho.\nTranslation mat karo. Agar audio aur user-specified language match nahi karta, to pronunciation match karte hue text likho.\nExample: Audio Hindi, user language English \u2192 English letters me likho, pronunciation Hindi jaisa.\nDefault behavior (language not specified):\nAgar user koi language specify nahi karta, to audio ki language automatically detect karo aur us language ke style mein hi transcript generate karo.\nKisi bhi language ko detect karke usi style mein natural aur realistic transcript produce karo.\nBackground noise handling:\nLow volume background sound ya irrelevant noise ignore karo.\nSirf clearly spoken, meaningful words capture karo.\nExact transcription:\nText exactly waise hi likho jaise bola gaya hai, stutters, hesitations, ya repeated words ke saath.\nPunctuation aur line breaks readability ke liye use kar sakte ho, lekin content strictly audio based hona chahiye.\nMulti-language or code-switching:\nAgar speaker multiple languages mix karta hai, ya Hinglish bolta hai, to user-specified language follow karo, ya default detection ke case me primary spoken language detect karke transcript banao.\nTransliteration rules apply kar sakte ho only for pronunciation matching.\nProfessional speech-to-text behavior:\nAct like a real transcription engine: natural, realistic, aur 100% accurate audio-to-text conversion.\nKabhi bhi apna opinion, extra content, ya summary add mat karo.\nOutput Examples:\nUser language Hindi:\nAudio: \"Hello, kaise ho? Main theek hoon.\"\nOutput: \"Hello, kaise ho? Main theek hoon.\"\nUser language English, audio Hindi:\nAudio: \"Mera naam Raj hai.\"\nOutput: \"Mera naam Raj hai.\" (English letters, pronunciation Hindi jaisa)\nNo user language specified (automatic detection):\nAudio: \"Bonjour, comment \u00E7a va?\"\nOutput: \"Bonjour, comment \u00E7a va?\" (French detected, transcript French style)\nHinglish audio, user language Hinglish:\nAudio: \"Good morning, doston!\"\nOutput: \"Good morning, doston!\"\nFocus 100% on accurate audio-to-text conversion with correct language style, pronunciation, and automatic detection. Background noise ignore karo, aur transcript ko natural aur realistic banao.";

package/dist/constants.js

@@ -0,0 +1,35 @@
+export const DEFAULT_SYSTEM_INSTRUCTION = `You are a speech-to-text AI model. Tumhara kaam sirf ye hai ki jo bhi audio mile, usko accurately text mein convert karo. Tumhe kuch bhi summarize, interpret, ya translate nahi karna hai—bas spoken words ka exact transcript generate karna hai.
+Rules/Instructions:
+User-specified language:
+Agar user language specify karta hai (Hindi, English, Hinglish, etc.), to text us language ke style mein hi likho.
+Translation mat karo. Agar audio aur user-specified language match nahi karta, to pronunciation match karte hue text likho.
+Example: Audio Hindi, user language English → English letters me likho, pronunciation Hindi jaisa.
+Default behavior (language not specified):
+Agar user koi language specify nahi karta, to audio ki language automatically detect karo aur us language ke style mein hi transcript generate karo.
+Kisi bhi language ko detect karke usi style mein natural aur realistic transcript produce karo.
+Background noise handling:
+Low volume background sound ya irrelevant noise ignore karo.
+Sirf clearly spoken, meaningful words capture karo.
+Exact transcription:
+Text exactly waise hi likho jaise bola gaya hai, stutters, hesitations, ya repeated words ke saath.
+Punctuation aur line breaks readability ke liye use kar sakte ho, lekin content strictly audio based hona chahiye.
+Multi-language or code-switching:
+Agar speaker multiple languages mix karta hai, ya Hinglish bolta hai, to user-specified language follow karo, ya default detection ke case me primary spoken language detect karke transcript banao.
+Transliteration rules apply kar sakte ho only for pronunciation matching.
+Professional speech-to-text behavior:
+Act like a real transcription engine: natural, realistic, aur 100% accurate audio-to-text conversion.
+Kabhi bhi apna opinion, extra content, ya summary add mat karo.
+Output Examples:
+User language Hindi:
+Audio: "Hello, kaise ho? Main theek hoon."
+Output: "Hello, kaise ho? Main theek hoon."
+User language English, audio Hindi:
+Audio: "Mera naam Raj hai."
+Output: "Mera naam Raj hai." (English letters, pronunciation Hindi jaisa)
+No user language specified (automatic detection):
+Audio: "Bonjour, comment ça va?"
+Output: "Bonjour, comment ça va?" (French detected, transcript French style)
+Hinglish audio, user language Hinglish:
+Audio: "Good morning, doston!"
+Output: "Good morning, doston!"
+Focus 100% on accurate audio-to-text conversion with correct language style, pronunciation, and automatic detection. Background noise ignore karo, aur transcript ko natural aur realistic banao.`;

package/dist/core.d.ts

@@ -0,0 +1,10 @@
+import { SSTOptions, TranscriptionResult } from './types.js';
+/**
+ * Processes audio using the Gemini API.
+ * @param audioData - Base64 encoded audio string
+ * @param mimeType - MIME type of the audio
+ * @param apiKey - Google Gemini API Key
+ * @param options - Configuration options
+ * @returns Promise resolving to the transcription result
+ */
+export declare function processAudioWithGemini(audioData: string, mimeType: string, apiKey: string, options: SSTOptions): Promise<TranscriptionResult>;

package/dist/core.js

@@ -0,0 +1,126 @@
+/**
+ * Core business logic using Google GenAI SDK
+ */
+import { GoogleGenAI } from '@google/genai';
+import { DEFAULT_SYSTEM_INSTRUCTION } from './constants.js';
+/**
+ * Processes audio using the Gemini API.
+ * @param audioData - Base64 encoded audio string
+ * @param mimeType - MIME type of the audio
+ * @param apiKey - Google Gemini API Key
+ * @param options - Configuration options
+ * @returns Promise resolving to the transcription result
+ */
+export async function processAudioWithGemini(audioData, mimeType, apiKey, options) {
+    if (!apiKey) {
+        throw new Error("API Key is required");
+    }
+    // Initialize the AI client according to documentation: new GoogleGenAI({ apiKey })
+    const ai = new GoogleGenAI({ apiKey: apiKey });
+    const modelName = options.model || "gemini-2.5-flash-lite";
+    // Configure thinking mode as per Gemini 2.5 specifications in documentation
+    const config = {
+        thinkingConfig: {
+            includeThoughts: true, // Enabled to allow monitoring thoughts if needed
+            thinkingBudget: -1 // Dynamic thinking enabled (-1)
+        },
+        // Fixed System Instruction: Users cannot override this as it is the core STT logic.
+        systemInstruction: DEFAULT_SYSTEM_INSTRUCTION
+    };
+    if (options.verbose) {
+        console.log(`[SSTLibrary] Model: ${modelName}`);
+        console.log(`[SSTLibrary] Thinking: Dynamic (-1)`);
+        console.log(`[SSTLibrary] System Instruction: Locked (Core)`);
+    }
+    const promptText = options.prompt || "Transcribe this audio.";
+    const startTime = Date.now();
+    try {
+        /**
+         * Using the syntax from the provided documentation:
+         * ai.models.generateContent({ model, contents, config })
+         */
+        const response = await ai.models.generateContent({
+            model: modelName,
+            contents: [
+                {
+                    role: "user",
+                    parts: [
+                        { text: promptText },
+                        {
+                            inlineData: {
+                                mimeType: mimeType,
+                                data: audioData
+                            }
+                        }
+                    ]
+                }
+            ],
+            config: config
+        });
+        const endTime = Date.now();
+        const processingTimeSec = parseFloat(((endTime - startTime) / 1000).toFixed(2));
+        // Handle the response according to the documentation structure
+        const candidate = response.candidates?.[0];
+        const textParts = candidate?.content?.parts || [];
+        // Combine text parts and thought parts separately
+        const transcriptText = textParts
+            .filter((p) => !p.thought)
+            .map((p) => p.text)
+            .join('') || "";
+        const thoughtText = textParts
+            .filter((p) => p.thought)
+            .map((p) => p.text)
+            .join('') || "";
+        // Extract usage details
+        const usage = response.usageMetadata ? {
+            inputTokens: response.usageMetadata.promptTokenCount || 0,
+            outputTokens: response.usageMetadata.candidatesTokenCount || 0,
+            totalTokens: response.usageMetadata.totalTokenCount || 0,
+            processingTimeSec: processingTimeSec
+        } : undefined;
+        return {
+            text: transcriptText,
+            thoughts: thoughtText,
+            model: modelName,
+            usage: usage
+        };
+    }
+    catch (error) {
+        // If the newer ai.models.generateContent syntax is not available in the installed SDK version,
+        // fallback to the widely supported getGenerativeModel method while keeping logic consistent.
+        if (options.verbose)
+            console.warn("[SSTLibrary] Newer syntax failed, trying fallback...");
+        try {
+            const model = ai.getGenerativeModel({ model: modelName }, config);
+            const result = await model.generateContent({
+                contents: [{
+                        role: 'user',
+                        parts: [
+                            { text: promptText },
+                            { inlineData: { mimeType, data: audioData } }
+                        ]
+                    }]
+            });
+            const endTime = Date.now();
+            const processingTimeSec = parseFloat(((endTime - startTime) / 1000).toFixed(2));
+            const resp = result.response;
+            const candidate = resp.candidates?.[0];
+            const parts = candidate?.content?.parts || [];
+            return {
+                text: parts.filter((p) => !p.thought).map((p) => p.text).join(''),
+                thoughts: parts.filter((p) => p.thought).map((p) => p.text).join(''),
+                model: modelName,
+                usage: resp.usageMetadata ? {
+                    inputTokens: resp.usageMetadata.promptTokenCount,
+                    outputTokens: resp.usageMetadata.candidatesTokenCount,
+                    totalTokens: resp.usageMetadata.totalTokenCount,
+                    processingTimeSec: processingTimeSec
+                } : undefined
+            };
+        }
+        catch (fallbackError) {
+            console.error("[SSTLibrary] Transcription failed:", fallbackError);
+            throw fallbackError;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { SSTOptions, TranscriptionResult } from './types.js';
+/**
+ * Node.js entry point
+ * @param audioFile Path to the audio file
+ * @param apiKey Google Gemini API Key
+ * @param options Configuration options
+ * @returns The transcription result object containing text and thoughts
+ */
+export declare function audioToText(audioFile: string, apiKey: string, options?: SSTOptions): Promise<TranscriptionResult>;
+export * from './types.js';

package/dist/index.js

@@ -0,0 +1,35 @@
+import { processAudioWithGemini } from './core.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { bufferToBase64 } from './utils.js';
+/**
+ * Node.js entry point
+ * @param audioFile Path to the audio file
+ * @param apiKey Google Gemini API Key
+ * @param options Configuration options
+ * @returns The transcription result object containing text and thoughts
+ */
+export async function audioToText(audioFile, apiKey, options = {}) {
+    // 1. Read Audio File
+    if (!fs.existsSync(audioFile)) {
+        throw new Error(`Audio file not found: ${audioFile}`);
+    }
+    // Simple mime type detection based on extension
+    const ext = path.extname(audioFile).toLowerCase().replace('.', '');
+    // Default map
+    const mimeMap = {
+        'mp3': 'audio/mp3',
+        'wav': 'audio/wav',
+        'ogg': 'audio/ogg',
+        'flac': 'audio/flac',
+        'aac': 'audio/aac',
+        'm4a': 'audio/m4a', // often parsed as mp4/aac
+        'mp4': 'audio/mp4'
+    };
+    const mimeType = mimeMap[ext] || 'audio/mp3'; // Default to mp3 if unknown
+    const fileBuffer = fs.readFileSync(audioFile);
+    const base64Audio = bufferToBase64(fileBuffer);
+    // 2. Process
+    return await processAudioWithGemini(base64Audio, mimeType, apiKey, options);
+}
+export * from './types.js';

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Common types for the SST Library
+ */
+export type AudioInput = string | File;
+export interface SSTOptions {
+    /**
+     * The text prompt to guide the audio processing (e.g., "Transcribe in Hindi", "In English letters").
+     */
+    prompt?: string;
+    /**
+     * Model to use. Defaults to "gemini-2.5-flash-lite".
+     */
+    model?: string;
+    /**
+     * Verbose logging.
+     */
+    verbose?: boolean;
+}
+export interface TranscriptionResult {
+    text: string;
+    thoughts?: string;
+    model: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        processingTimeSec: number;
+    };
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Common types for the SST Library
+ */
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Utility functions
+ */
+export declare function isNode(): boolean;
+export declare function isBrowser(): boolean;
+/**
+ * Converts a File object (Browser) to a Base64 string.
+ */
+export declare function fileToBase64(file: File): Promise<string>;
+/**
+ * Converts a NodeJS Buffer to a Base64 string.
+ */
+export declare function bufferToBase64(buffer: Buffer): string;

package/dist/utils.js

@@ -0,0 +1,35 @@
+/**
+ * Utility functions
+ */
+export function isNode() {
+    return typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
+}
+export function isBrowser() {
+    return typeof window !== 'undefined' && typeof window.document !== 'undefined';
+}
+/**
+ * Converts a File object (Browser) to a Base64 string.
+ */
+export async function fileToBase64(file) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.readAsDataURL(file);
+        reader.onload = () => {
+            if (typeof reader.result === 'string') {
+                // Remove the Data-URL declaration (e.g., "data:audio/mp3;base64,")
+                const base64 = reader.result.split(',')[1];
+                resolve(base64);
+            }
+            else {
+                reject(new Error('Failed to convert file to base64'));
+            }
+        };
+        reader.onerror = error => reject(error);
+    });
+}
+/**
+ * Converts a NodeJS Buffer to a Base64 string.
+ */
+export function bufferToBase64(buffer) {
+    return buffer.toString('base64');
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "geminisst",
+  "version": "1.0.0",
+  "description": "Revolutionary high-accuracy Audio-to-Text library powered by Gemini 2.5 Flash Lite with 1M+ context window.",
+  "keywords": [
+    "sst",
+    "stt",
+    "gemini",
+    "audio-to-text",
+    "transcription",
+    "multimodal",
+    "ai",
+    "google-genai"
+  ],
+  "license": "ISC",
+  "author": "Smart Tell Line",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "node examples/test_node.js",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@google/genai": "*",
+    "dotenv": "^16.4.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}