Usage

The Sofya Transcription SDK provides a robust and flexible solution for real-time audio transcription. This guide will help you get started with using the SDK in your projects.

Basic Usage

Here's a basic example of how to use Sofya Transcription in your project:

1. Import the Library:

   import { MediaElementAudioCapture, SofyaTranscriber } from 'sofya.transcription';

2. Create a Transcription Service Instance:

   // Using API key connection
   const transcriber = new SofyaTranscriber({
     apiKey: 'YOUR_API_KEY',
     config: {
       language: 'en-US'
     }
   });
   
   // Or using a specific provider
   const transcriber = new SofyaTranscriber({
     provider: 'sofya_compliance',
     endpoint: 'YOUR_ENDPOINT',
     config: {
       language: 'en-US',
       token: 'YOUR_TOKEN',
       compartmentId: 'YOUR_COMPARTMENT_ID',
       region: 'YOUR_REGION'
     }
   });

3. Initialize and Start Transcription:

   // Wait for the transcriber to be ready
   transcriber.on('ready', () => {
     // Get media stream
     navigator.mediaDevices.getUserMedia({ audio: true })
       .then(mediaStream => {
         // Start transcription
         transcriber.startTranscription(mediaStream);
       })
       .catch(error => {
         console.error('Error accessing microphone:', error);
       });
   });

4. Handle Transcription Events:

   transcriber.on('recognizing', (text) => {
     console.log('Recognizing: ' + text);
   });
   
   transcriber.on('recognized', (text) => {
     console.log('Recognized: ' + text);
   });
   
   transcriber.on('error', (error) => {
     console.error('Transcription error:', error);
   });
   
   transcriber.on('stopped', () => {
     console.log('Transcription stopped');
   });

5. Control Transcription:

   // Pause transcription
   transcriber.pauseTranscription();
   
   // Resume transcription
   transcriber.resumeTranscription();
   
   // Stop transcription
   transcriber.stopTranscription();

Error Handling

The Sofya Transcription SDK provides comprehensive error handling to ensure a robust and reliable transcription experience. The SDK uses a combination of error throwing, event emission, and logging to handle errors at different stages of the transcription process.

Error Handling Strategies

1. Validation Errors

   • Missing API key
   • Missing endpoint for provider connection
   • Missing configuration for provider connection
   • Invalid connection object

2. Connection Errors

   • Authentication failure
   • Network connectivity issues
   • Provider service unavailability
   • Invalid provider configuration

3. Transcription Errors

   • Microphone access denied
   • Audio processing errors
   • Provider service errors during transcription

Best Practices for Error Handling

1. Always Listen for Error Events

   transcriber.on('error', (error) => {
     console.error('Transcription error:', error);
     // Handle the error appropriately
   });

2. Use Try-Catch Blocks for Initialization

   try {
     const transcriber = new SofyaTranscriber({
       apiKey: 'YOUR_API_KEY',
       config: {
         language: 'en-US'
       }
     });
     
     // Use the transcriber
   } catch (error) {
     console.error('Failed to initialize transcriber:', error);
     // Handle the error appropriately
   }

3. Check for Ready Event Before Starting Transcription

   transcriber.on('ready', () => {
     console.log('Transcription service is ready');
     
     // Get media stream and start transcription
     navigator.mediaDevices.getUserMedia({ audio: true })
       .then(mediaStream => {
         transcriber.startTranscription(mediaStream);
       })
       .catch(error => {
         console.error('Error accessing microphone:', error);
         // Handle the error appropriately
       });
   });

4. Implement Retry Logic for Critical Operations

   function startTranscriptionWithRetry(transcriber, mediaStream, maxRetries = 3) {
     let retryCount = 0;
     
     function attemptStart() {
       try {
         transcriber.startTranscription(mediaStream);
       } catch (error) {
         console.error(`Failed to start transcription (attempt ${retryCount + 1}/${maxRetries}):`, error);
         
         if (retryCount < maxRetries) {
           retryCount++;
           setTimeout(attemptStart, 1000); // Retry after 1 second
         } else {
           console.error('Failed to start transcription after multiple attempts');
           // Handle the error appropriately
         }
       }
     }
     
     attemptStart();
   }

Common Error Scenarios and Solutions

1. API Key Authentication Failure

   • Error Message: "Could not authenticate. Please validate your API key and try again."
   • Solution: Verify that the API key is correct and has not expired. If the issue persists, contact Sofya support.

2. Provider Connection Failure

   • Error Message: "Failed to connect to any provider. Please check your API key and try again."
   • Solution: Check your network connectivity and verify that the provider services are available. If the issue persists, try using a different provider or contact Sofya support.

3. Microphone Access Denied

   • Error Message: "Error accessing microphone: NotAllowedError"
   • Solution: Ensure that the user has granted permission to access the microphone. If the permission was denied, the user will need to grant permission through their browser settings.

4. Transcription Service Error

   • Error Message: "Transcription service error: [provider-specific error]"
   • Solution: Check the provider-specific error message for details. Common issues include invalid configuration, network connectivity problems, or provider service unavailability.