@speechall/sdk 1.0.0 → 2.0.4

package/examples/advanced-options.ts

@@ -0,0 +1,213 @@
+/**
+ * Advanced Options Example
+ *
+ * This example demonstrates how to use advanced transcription features including:
+ * - Speaker diarization (identifying different speakers)
+ * - Word-level timestamps
+ * - Custom vocabulary
+ * - Temperature control
+ * - Initial prompts for context
+ * - Different output formats (SRT, VTT)
+ */
+
+import 'dotenv/config';
+import { SpeechallClient } from '../src/index';
+import * as fs from 'fs';
+import * as path from 'path';
+
+async function main() {
+  const client = new SpeechallClient({
+    token: process.env.SPEECHALL_API_KEY!,
+  });
+
+  const audioFilePath = path.join(__dirname, 'sample-audio.wav');
+
+  if (!fs.existsSync(audioFilePath)) {
+    console.error(`Audio file not found at: ${audioFilePath}`);
+    console.error('Please provide a valid audio file path.');
+    process.exit(1);
+  }
+
+  console.log('=== Advanced Transcription Examples ===\n');
+
+  // Example 1: Transcription with speaker diarization and word-level timestamps
+  console.log('1. Transcription with Speaker Diarization and Word Timestamps');
+  console.log('-----------------------------------------------------------');
+
+  try {
+    const audioFile1 = fs.createReadStream(audioFilePath);
+
+    const response1 = await client.speechToText.transcribe(
+      audioFile1,
+      {
+        model: 'deepgram.nova-2', // Deepgram supports advanced features
+        language: 'en',
+        output_format: 'json', // Detailed output with timestamps
+        diarization: true, // Enable speaker identification
+        timestamp_granularity: 'word', // Word-level timestamps (vs 'segment')
+        punctuation: true,
+      }
+    );
+
+    console.log('Result:', JSON.stringify(response1, null, 2));
+    console.log('\n');
+
+  } catch (error) {
+    console.error('Example 1 failed:', error);
+  }
+
+  // Example 2: Using custom vocabulary for better recognition
+  console.log('2. Transcription with Custom Vocabulary');
+  console.log('----------------------------------------');
+
+  try {
+    const audioFile2 = fs.createReadStream(audioFilePath);
+
+    const response2 = await client.speechToText.transcribe(
+      audioFile2,
+      {
+        model: 'assemblyai.best',
+        language: 'en',
+        output_format: 'json',
+        // Provide domain-specific words for better recognition
+        custom_vocabulary: ['Speechall', 'API', 'TypeScript', 'SDK'],
+        punctuation: true,
+      }
+    );
+
+    console.log('Result:', JSON.stringify(response2, null, 2));
+    console.log('\n');
+
+  } catch (error) {
+    console.error('Example 2 failed:', error);
+  }
+
+  // Example 3: Using initial prompt for context and style
+  console.log('3. Transcription with Initial Prompt (Context)');
+  console.log('-----------------------------------------------');
+
+  try {
+    const audioFile3 = fs.createReadStream(audioFilePath);
+
+    const response3 = await client.speechToText.transcribe(
+      audioFile3,
+      {
+        model: 'openai.whisper-1',
+        language: 'en',
+        output_format: 'text',
+        // Provide context to improve accuracy and style
+        initial_prompt: 'This is a technical discussion about software development and APIs.',
+        temperature: 0.2, // Lower temperature for more deterministic output
+      }
+    );
+
+    console.log('Result:', response3);
+    console.log('\n');
+
+  } catch (error) {
+    console.error('Example 3 failed:', error);
+  }
+
+  // Example 4: Generate SRT subtitles
+  console.log('4. Generate SRT Subtitles');
+  console.log('-------------------------');
+
+  try {
+    const audioFile4 = fs.createReadStream(audioFilePath);
+
+    const response4 = await client.speechToText.transcribe(
+      audioFile4,
+      {
+        model: 'openai.whisper-1',
+        language: 'en',
+        output_format: 'srt', // SRT subtitle format
+      }
+    );
+
+    console.log('SRT Output:');
+    console.log(response4);
+    console.log('\n');
+
+    // You can save this to a file
+    // fs.writeFileSync('subtitles.srt', response4 as string);
+
+  } catch (error) {
+    console.error('Example 4 failed:', error);
+  }
+
+  // Example 5: Generate VTT subtitles
+  console.log('5. Generate VTT Subtitles');
+  console.log('-------------------------');
+
+  try {
+    const audioFile5 = fs.createReadStream(audioFilePath);
+
+    const response5 = await client.speechToText.transcribe(
+      audioFile5,
+      {
+        model: 'openai.whisper-1',
+        language: 'en',
+        output_format: 'vtt', // WebVTT subtitle format
+      }
+    );
+
+    console.log('VTT Output:');
+    console.log(response5);
+    console.log('\n');
+
+  } catch (error) {
+    console.error('Example 5 failed:', error);
+  }
+
+  // Example 6: Using smart formatting (Deepgram feature)
+  console.log('6. Transcription with Smart Formatting');
+  console.log('---------------------------------------');
+
+  try {
+    const audioFile6 = fs.createReadStream(audioFilePath);
+
+    const response6 = await client.speechToText.transcribe(
+      audioFile6,
+      {
+        model: 'deepgram.nova-2',
+        language: 'en',
+        output_format: 'json',
+        smart_format: true, // Format numbers, dates, currency, etc.
+        punctuation: true,
+      }
+    );
+
+    console.log('Result:', JSON.stringify(response6, null, 2));
+    console.log('\n');
+
+  } catch (error) {
+    console.error('Example 6 failed:', error);
+  }
+
+  // Example 7: Specify expected number of speakers
+  console.log('7. Transcription with Expected Speaker Count');
+  console.log('---------------------------------------------');
+
+  try {
+    const audioFile7 = fs.createReadStream(audioFilePath);
+
+    const response7 = await client.speechToText.transcribe(
+      audioFile7,
+      {
+        model: 'deepgram.nova-2',
+        language: 'en',
+        output_format: 'json',
+        diarization: true,
+        speakers_expected: 2, // Hint: expect 2 speakers in the audio
+      }
+    );
+
+    console.log('Result:', JSON.stringify(response7, null, 2));
+
+  } catch (error) {
+    console.error('Example 7 failed:', error);
+  }
+}
+
+// Run the examples
+main();

package/examples/basic-transcription.ts

@@ -0,0 +1,66 @@
+/**
+ * Basic Transcription Example
+ *
+ * This example demonstrates how to transcribe a local audio file using the Speechall SDK.
+ * It shows the simplest way to get started with speech-to-text transcription.
+ */
+
+import 'dotenv/config';
+import { SpeechallClient } from '../src/index';
+import * as fs from 'fs';
+import * as path from 'path';
+
+async function main() {
+  // Initialize the Speechall client with your API token
+  const client = new SpeechallClient({
+    token: process.env.SPEECHALL_API_KEY!,
+  });
+
+  // Path to your audio file
+  // Replace this with the path to your actual audio file
+  const audioFilePath = path.join(__dirname, 'sample-audio.wav');
+
+  // Check if file exists
+  if (!fs.existsSync(audioFilePath)) {
+    console.error(`Audio file not found at: ${audioFilePath}`);
+    console.error('Please provide a valid audio file path.');
+    process.exit(1);
+  }
+
+  console.log('Transcribing audio file...');
+  console.log(`File: ${audioFilePath}`);
+
+  try {
+    // Read the audio file
+    const audioFile = fs.createReadStream(audioFilePath);
+
+    // Transcribe the audio using the default settings
+    // This will return plain text output
+    const response = await client.speechToText.transcribe(
+      audioFile,
+      {
+        model: 'openai.whisper-1', // Using OpenAI's Whisper model
+        language: 'en', // English language
+        output_format: 'text', // Plain text output
+      }
+    );
+
+    // Display the transcription result
+    console.log('\n--- Transcription Result ---');
+
+    // The response can be either a string (text format) or an object (json format)
+    if (typeof response === 'string') {
+      console.log(response);
+    } else {
+      console.log(JSON.stringify(response, null, 2));
+    }
+
+  } catch (error) {
+    console.error('Transcription failed:');
+    console.error(error);
+    process.exit(1);
+  }
+}
+
+// Run the example
+main();

package/examples/error-handling.ts

@@ -0,0 +1,251 @@
+/**
+ * Error Handling Example
+ *
+ * This example demonstrates proper error handling when using the Speechall SDK.
+ * It shows how to catch and handle different types of errors that may occur
+ * during API calls.
+ */
+
+import 'dotenv/config';
+import { SpeechallClient, SpeechallError } from '../src/index';
+import * as Speechall from '../src/api/index';
+import * as fs from 'fs';
+import * as path from 'path';
+
+async function main() {
+  console.log('=== Error Handling Examples ===\n');
+
+  // Example 1: Handling authentication errors
+  console.log('1. Authentication Error');
+  console.log('-----------------------');
+
+  try {
+    const clientWithBadToken = new SpeechallClient({
+      token: 'invalid-token',
+    });
+
+    const audioFile = fs.createReadStream(path.join(__dirname, 'sample-audio.wav'));
+
+    await clientWithBadToken.speechToText.transcribe(
+      audioFile,
+      {
+        model: 'openai.whisper-1',
+      }
+    );
+
+  } catch (error) {
+    if (error instanceof Speechall.UnauthorizedError) {
+      console.error('Authentication failed!');
+      console.error('Status:', error.statusCode);
+      console.error('Message:', error.message);
+      console.error('Details:', error.body);
+    } else {
+      console.error('Unexpected error:', error);
+    }
+  }
+  console.log('\n');
+
+  // Example 2: Handling bad request errors (invalid parameters)
+  console.log('2. Bad Request Error');
+  console.log('--------------------');
+
+  try {
+    const client = new SpeechallClient({
+      token: process.env.SPEECHALL_API_KEY!,
+    });
+
+    const audioFile = fs.createReadStream(path.join(__dirname, 'sample-audio.wav'));
+
+    // Intentionally use an invalid model to trigger an error
+    await client.speechToText.transcribe(
+      audioFile,
+      {
+        model: 'invalid.model' as any,
+      }
+    );
+
+  } catch (error) {
+    if (error instanceof Speechall.BadRequestError) {
+      console.error('Bad request!');
+      console.error('Status:', error.statusCode);
+      console.error('Message:', error.message);
+      console.error('Details:', error.body);
+    } else if (error instanceof SpeechallError) {
+      console.error('API Error:', error.message);
+    } else {
+      console.error('Unexpected error:', error);
+    }
+  }
+  console.log('\n');
+
+  // Example 3: Handling rate limit errors
+  console.log('3. Rate Limit Error');
+  console.log('-------------------');
+
+  try {
+    const client = new SpeechallClient({
+      token: process.env.SPEECHALL_API_KEY!,
+    });
+
+    // Make multiple rapid requests to potentially trigger rate limiting
+    // (In real scenarios, you'd implement proper rate limiting on your side)
+    const audioFile = fs.createReadStream(path.join(__dirname, 'sample-audio.wav'));
+
+    await client.speechToText.transcribe(
+      audioFile,
+      {
+        model: 'openai.whisper-1',
+      }
+    );
+
+  } catch (error) {
+    if (error instanceof Speechall.TooManyRequestsError) {
+      console.error('Rate limit exceeded!');
+      console.error('Status:', error.statusCode);
+      console.error('Message:', error.message);
+      console.error('Please wait before retrying.');
+      // In production, implement exponential backoff
+    } else {
+      console.error('Error:', error);
+    }
+  }
+  console.log('\n');
+
+  // Example 4: Handling file not found errors
+  console.log('4. File Not Found Error');
+  console.log('-----------------------');
+
+  try {
+    const client = new SpeechallClient({
+      token: process.env.SPEECHALL_API_KEY!,
+    });
+
+    // Try to transcribe a non-existent remote file
+    await client.speechToText.transcribeRemote({
+      file_url: 'https://dss-kiel.de/images/media_center/signals/lombard/male_0_kmh.mp3',
+      model: 'openai.whisper-1',
+    });
+
+  } catch (error) {
+    if (error instanceof Speechall.NotFoundError) {
+      console.error('Resource not found!');
+      console.error('Status:', error.statusCode);
+      console.error('Message:', error.message);
+    } else {
+      console.error('Error:', error);
+    }
+  }
+  console.log('\n');
+
+  // Example 5: Comprehensive error handling with retry logic
+  console.log('5. Comprehensive Error Handling with Retry');
+  console.log('-------------------------------------------');
+
+  await transcribeWithRetry(
+    path.join(__dirname, 'sample-audio.wav'),
+    3 // Max retries
+  );
+}
+
+/**
+ * Helper function demonstrating retry logic with exponential backoff
+ */
+async function transcribeWithRetry(
+  audioPath: string,
+  maxRetries: number = 3
+): Promise<void> {
+  const client = new SpeechallClient({
+    token: process.env.SPEECHALL_API_KEY!,
+  });
+
+  let retries = 0;
+  let delay = 1000; // Start with 1 second delay
+
+  while (retries < maxRetries) {
+    try {
+      if (!fs.existsSync(audioPath)) {
+        console.log('Audio file not found. Creating a dummy request for demonstration.');
+        // For demo purposes, just show the error handling structure
+        throw new Error('File not found');
+      }
+
+      const audioFile = fs.createReadStream(audioPath);
+
+      const response = await client.speechToText.transcribe(
+        audioFile,
+        {
+          model: 'openai.whisper-1',
+          language: 'en',
+        }
+      );
+
+      console.log('Transcription successful!');
+      console.log('Result:', response);
+      return; // Success, exit the function
+
+    } catch (error) {
+      retries++;
+
+      // Handle different error types
+      if (error instanceof Speechall.TooManyRequestsError) {
+        console.error(`Rate limited. Retry ${retries}/${maxRetries} after ${delay}ms...`);
+
+        if (retries < maxRetries) {
+          await sleep(delay);
+          delay *= 2; // Exponential backoff
+        }
+
+      } else if (error instanceof Speechall.InternalServerError ||
+                 error instanceof Speechall.ServiceUnavailableError ||
+                 error instanceof Speechall.GatewayTimeoutError) {
+        console.error(`Server error. Retry ${retries}/${maxRetries} after ${delay}ms...`);
+        console.error('Error:', error.message);
+
+        if (retries < maxRetries) {
+          await sleep(delay);
+          delay *= 2; // Exponential backoff
+        }
+
+      } else if (error instanceof Speechall.UnauthorizedError) {
+        console.error('Authentication failed. Cannot retry.');
+        console.error('Please check your API key.');
+        throw error; // Don't retry authentication errors
+
+      } else if (error instanceof Speechall.BadRequestError) {
+        console.error('Bad request. Cannot retry.');
+        console.error('Please check your request parameters.');
+        throw error; // Don't retry bad requests
+
+      } else if (error instanceof Speechall.PaymentRequiredError) {
+        console.error('Payment required. Cannot retry.');
+        console.error('Please check your account billing.');
+        throw error; // Don't retry payment errors
+
+      } else if (error instanceof SpeechallError) {
+        console.error('API Error:', error.message);
+        throw error;
+
+      } else {
+        console.error('Unexpected error:', error);
+        throw error;
+      }
+    }
+  }
+
+  console.error(`Max retries (${maxRetries}) exceeded. Giving up.`);
+  throw new Error('Transcription failed after retries');
+}
+
+/**
+ * Helper function to sleep for a given duration
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// Run the examples
+main().catch(error => {
+  console.error('Example script failed:');
+  console.error(error);
+  process.exit(1);
+});

package/examples/list-models.ts

@@ -0,0 +1,112 @@
+/**
+ * List Available Models Example
+ *
+ * This example demonstrates how to retrieve and display all available
+ * speech-to-text models from the Speechall API.
+ * Use this to discover what models are available and their capabilities.
+ */
+
+import 'dotenv/config';
+import { SpeechallClient } from '../src/index';
+
+async function main() {
+  // Initialize the Speechall client with your API token
+  const client = new SpeechallClient({
+    token: process.env.SPEECHALL_API_KEY!,
+  });
+
+  console.log('Fetching available speech-to-text models...\n');
+
+  try {
+    // Get the list of all available models
+    const models = await client.speechToText.listSpeechToTextModels();
+
+    console.log(`Found ${models.length} available models:\n`);
+    console.log('='.repeat(80));
+
+    // Display each model's information
+    models.forEach((model, index) => {
+      console.log(`\n${index + 1}. ${model.display_name}`);
+      console.log('-'.repeat(80));
+
+      // Display model identifier
+      if (model.id) {
+        console.log(`   Identifier: ${model.id}`);
+      }
+
+      // Display provider
+      if (model.provider) {
+        console.log(`   Provider: ${model.provider}`);
+      }
+
+      // Display description
+      if (model.description) {
+        console.log(`   Description: ${model.description}`);
+      }
+
+      // Display supported languages
+      if (model.supported_languages && Array.isArray(model.supported_languages)) {
+        console.log(`   Supported Languages: ${model.supported_languages.join(', ')}`);
+      }
+
+      // Display cost
+      if (model.cost_per_second_usd) {
+        console.log(`   Cost per second: $${model.cost_per_second_usd}`);
+      }
+
+      // Display availability
+      console.log(`   Available: ${model.is_available ? 'Yes' : 'No'}`);
+
+      // Display feature support
+      console.log('   Features:');
+
+      if (typeof model.punctuation === 'boolean') {
+        console.log(`     - Punctuation: ${model.punctuation ? 'Yes' : 'No'}`);
+      }
+
+      if (typeof model.diarization === 'boolean') {
+        console.log(`     - Speaker Diarization: ${model.diarization ? 'Yes' : 'No'}`);
+      }
+
+      if (typeof model.word_timestamps === 'boolean') {
+        console.log(`     - Word Timestamps: ${model.word_timestamps ? 'Yes' : 'No'}`);
+      }
+
+      if (typeof model.custom_vocabulary_support === 'boolean') {
+        console.log(`     - Custom Vocabulary: ${model.custom_vocabulary_support ? 'Yes' : 'No'}`);
+      }
+
+      if (typeof model.streamable === 'boolean') {
+        console.log(`     - Streamable: ${model.streamable ? 'Yes' : 'No'}`);
+      }
+
+      // Display subtitle format support
+      console.log(`     - SRT Format: ${model.supports_srt ? 'Yes' : 'No'}`);
+      console.log(`     - VTT Format: ${model.supports_vtt ? 'Yes' : 'No'}`);
+
+      // Display performance characteristics
+      if (model.real_time_factor) {
+        console.log(`   Real-time Factor: ${model.real_time_factor}x`);
+      }
+
+      if (model.accuracy_tier) {
+        console.log(`   Accuracy Tier: ${model.accuracy_tier}`);
+      }
+
+      if (model.model_type) {
+        console.log(`   Model Type: ${model.model_type}`);
+      }
+    });
+
+    console.log('\n' + '='.repeat(80));
+    console.log('\nTo use a model, reference it by its identifier (e.g., "openai.whisper-1")');
+
+  } catch (error) {
+    console.error('Failed to fetch models:');
+    console.error(error);
+    process.exit(1);
+  }
+}
+
+// Run the example
+main();

package/examples/remote-transcription.ts

@@ -0,0 +1,60 @@
+/**
+ * Remote Transcription Example
+ *
+ * This example demonstrates how to transcribe an audio file from a publicly accessible URL.
+ * This is useful when your audio files are already hosted online (e.g., on S3, CDN, etc.).
+ */
+
+import 'dotenv/config';
+import { SpeechallClient } from '../src/index';
+
+async function main() {
+  // Initialize the Speechall client with your API token
+  const client = new SpeechallClient({
+    token: process.env.SPEECHALL_API_KEY!,
+  });
+
+  // URL of the audio file to transcribe
+  // Replace this with your own publicly accessible audio URL
+  const audioUrl = 'https://example.com/path/to/audio.mp3';
+
+  console.log('Transcribing remote audio file...');
+  console.log(`URL: ${audioUrl}`);
+
+  try {
+    // Transcribe the remote audio file
+    const response = await client.speechToText.transcribeRemote({
+      file_url: audioUrl,
+      model: 'openai.whisper-1',
+      language: 'en',
+      output_format: 'json', // Request JSON output for detailed information
+      punctuation: true, // Enable automatic punctuation
+    });
+
+    console.log('\n--- Transcription Result ---');
+
+    // When using JSON output format, the response contains detailed information
+    if (typeof response === 'string') {
+      console.log(response);
+    } else {
+      // The response object structure depends on the output format
+      // For 'json' format, it includes the text and metadata
+      console.log('Full response:');
+      console.log(JSON.stringify(response, null, 2));
+
+      // If the response has a text property, display it separately
+      if ('text' in response) {
+        console.log('\n--- Text Only ---');
+        console.log(response.text);
+      }
+    }
+
+  } catch (error) {
+    console.error('Transcription failed:');
+    console.error(error);
+    process.exit(1);
+  }
+}
+
+// Run the example
+main();

package/fern/fern.config.json

@@ -0,0 +1,4 @@
+{
+  "organization": "speechall",
+  "version": "3.23.2"
+}