sofya.transcription/Readme.md

a JavaScript library that provides a robust and flexible solution for real-time audio transcription. It is designed to transcribe audio streams and can be easily integrated into web applications.

# Sofya Transcription

**Sofya Transcription** is a JavaScript library that provides a robust and flexible solution for real-time audio transcription. It is designed to transcribe audio streams and can be easily integrated into web applications. The library also includes a functionality for capturing audio from media elements.

## Features

-   **Real-Time Transcription**: Transcribe audio streams in real time with high accuracy.
-   **Flexible Integration**: Seamlessly integrates with your web applications.
-   **Media Element Audio Capture**: Feature to capture audio from media elements like `<video>` and `<audio>`.

## Installation

To install **Sofya Transcription**, you can use npm:

`npm install sofya.transcription` 

## Usage

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

1.  **Import the Library**:
    
    `import { MediaElementAudioCapture, TranscriptionService } from 'sofya.transcription';` 
    
2.  **Create a Transcription Service Instance**:
    `const transcriptionConfig = {language: 'pt-BR', model: 'YOUR_MODEL_ID', region: 'YOUR_REGION'}`
    `const transcriber = new TranscriptionService('YOUR_API_KEY', transcriptionConfig);` 
    
3.  **Initialize and Start Transcription**:
 
    `const mediaStream = await navigator.mediaDevices.getUserMedia();` 
    `transcriber.startTranscription(mediaStream);` 
    
4.  **Handle Transcription Events**:
    
    `transcriber.on('recognizing', (text) => {`
     ` console.log('Recognizing: ' + text);
    });`
    
    `transcriber.on('recognized', (text) => {`
    `  console.log('Recognized: ' + text);`
   ` });`
    
    `transcriber.on('nomatch', () => {`
   `   console.log('No match found.');`
   ` });` 
    
5.  **Stop Transcription**:
        
    `transcriber.stopTranscription();` 
    

## API

### `TranscriptionService`

-   **constructor('YOUR_API_KEY', config)**: Creates a new instance of the transcription service with a given `API KEY` and an config object. 
    
-   **startTranscription(mediaStream): void**: Starts the transcription process with a given `MediaStream`.
    
-   **stopTranscription(): void**: Stops the transcription process.

-   **pauseTranscription(): void**: Pauses the transcription process.
    
-   **resumeTranscription(): void**: Resumes the transcription process.
    
-   **on(event: string, callback: Function): void**: Registers an event handler for transcription events. Possible events include:
    
    -   `recognizing`: Fired when transcription is in progress.
    -   `recognized`: Fired when transcription is complete.
    -   `nomatch`: Fired when no speech is recognized.

- **React Example**
```js
import React from 'react'
import { SofyaTranscriber } from 'sofya.transcription'
const App = () => {
  const transcriberRef = React.useRef<SofyaTranscriber | null>(null)
  const [transcription, setTranscription] = React.useState('')
  const transcriptionRef = React.useRef('')

  const getMediaStream = async () => {
    const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
    return stream
  }

  const startTranscription = async () => {
    try {
      const stream = await getMediaStream()
      const transcriber = new SofyaTranscriber(
        'your_key',
        {
          language: 'pt-BR',
        }
      )

      transcriber.on("ready", () => {
        transcriber.startTranscription(stream)
      })
      transcriber.on('recognizing', (result: string) => {
        console.log({ recognizing: result })
        setTranscription(transcriptionRef.current + result)
      })

      transcriber.on('recognized', (result: string) => {
        console.log({ recognized: result })
        setTranscription(transcriptionRef.current + result)
        transcriptionRef.current = transcriptionRef.current + result
      })
      transcriberRef.current = transcriber
    } catch (error) {
      console.log({ error })
    }
  }

  const stopTranscription = () => {
    if (transcriberRef.current) {
      transcriberRef.current.stopTranscription()
      transcriberRef.current = null
    }
  }

  return (
    <div>
      <button onClick={startTranscription}>Start Transcription</button>
      <button onClick={stopTranscription}>Stop Transcription</button>
      <hr />
      <p>{transcription}</p>
    </div>
  )
}

export default App
```
    

### `MediaElementAudioCapture`

-   **constructor()**: Creates a new instance of the media element audio capture.
    
-   **captureAudio(mediaElement: HTMLMediaElement): MediaStream**: Captures the audio stream from a given media element and returns a `MediaStream`.