### curl: STT Examples

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

This section provides command-line examples using curl to interact with the Speech-to-Text API for various transcription scenarios, including different engines, formats, and options.

```APIDOC
## API Endpoints Examples (curl)

### Compact STT (English, fast)

**Method:** POST
**Endpoint:** `https://apim-ai-apis.azure-api.net/v1/stt/transcribe/base64`

**Description:** Transcribes audio using the Compact STT engine, suitable for faster processing and English language.

**Request Example:**
```bash
API_KEY="YOUR_KEY"
curl -X POST "https://apim-ai-apis.azure-api.net/v1/stt/transcribe/base64" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: $API_KEY" \
  -d "{\"audio\": \"$(base64 -i audio.wav)\", \"include_timestamps\": true}" \
  | python3 -m json.tool
```

### Whisper Pro (multilingual)

**Method:** POST
**Endpoint:** `https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64`

**Description:** Transcribes audio using the Whisper model, supporting multiple languages and speaker diarization.

**Request Example:**
```bash
API_KEY="YOUR_KEY"
curl -X POST "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: $API_KEY" \
  -d "{\"audio\": \"$(base64 -i meeting.wav)\", \"language\": \"en\", \"diarize\": true}" \
  | python3 -m json.tool
```

### Whisper multipart upload

**Method:** POST
**Endpoint:** `https://apim-ai-apis.azure-api.net/v1/whisper/transcribe`

**Description:** Uploads an audio file directly using multipart/form-data for transcription with the Whisper model.

**Request Example:**
```bash
API_KEY="YOUR_KEY"
curl -X POST "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe" \
  -H "Ocp-Apim-Subscription-Key: $API_KEY" \
  -F "audio=@podcast.mp3" \
  -F "language=en" \
  -F "diarize=true" \
  | python3 -m json.tool
```

### Health check

**Method:** GET
**Endpoint:** `https://apim-ai-apis.azure-api.net/v1/whisper/health`

**Description:** Checks the health status of the Whisper transcription service.

**Request Example:**
```bash
API_KEY="YOUR_KEY"
curl -s "https://apim-ai-apis.azure-api.net/v1/whisper/health" \
  -H "Ocp-Apim-Subscription-Key: $API_KEY" | python3 -m json.tool
```
```

--------------------------------

### STT API Examples (curl)

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

This section provides command-line examples using `curl` to interact with Speech-to-Text APIs. It demonstrates transcription using different engines (Compact, Whisper), including options for language and speaker diarization, and shows how to perform a health check.

```bash
API_KEY="YOUR_KEY"

# Compact STT (English, fast)
curl -X POST "https://apim-ai-apis.azure-api.net/v1/stt/transcribe/base64" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: $API_KEY" \
  -d "{\"audio\": \"$(base64 -i audio.wav)\", \"include_timestamps\": true}" \
  | python3 -m json.tool

# Whisper Pro (multilingual)
curl -X POST "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: $API_KEY" \
  -d "{\"audio\": \"$(base64 -i meeting.wav)\", \"language\": \"en\", \"diarize\": true}" \
  | python3 -m json.tool

# Whisper multipart upload
curl -X POST "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe" \
  -H "Ocp-Apim-Subscription-Key: $API_KEY" \
  -F "audio=@podcast.mp3" \
  -F "language=en" \
  -F "diarize=true" \
  | python3 -m json.tool

# Health check
curl -s "https://apim-ai-apis.azure-api.net/v1/whisper/health" \
  -H "Ocp-Apim-Subscription-Key: $API_KEY" | python3 -m json.tool
```

--------------------------------

### Python Whisper Multilingual Transcription with Diarization

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Demonstrates how to perform multilingual transcription using the Whisper model via a REST API. This example shows how to send audio data in base64 format, enable speaker diarization, and automatically detect the language of the audio. It then processes the results to display the transcript with speaker labels.

```python
import requests
import base64

API_KEY = "YOUR_KEY"
HEADERS = {"Ocp-Apim-Subscription-Key": API_KEY, "Content-Type": "application/json"}

with open("meeting.wav", "rb") as f:
    audio_b64 = base64.b64encode(f.read()).decode()

# Auto-detect language, enable speaker diarization
response = requests.post(
    "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64",
    headers=HEADERS,
    json={
        "audio": audio_b64,
        "diarize": True,
        "format": "wav"
    }
)

result = response.json()
print(f"Detected language: {result['metadata']['language']}")
print(f"Processing time: {result['metadata']['processingTimeMs']}ms")
print(f"\nTranscript:")

current_speaker = None
for word in result["words"]:
    if word.get("speaker") != current_speaker:
        current_speaker = word.get("speaker")
        print(f"\n[{current_speaker}]: ", end="")
    print(f"{word['word']} ", end="")

```

--------------------------------

### Whisper Multilingual Transcription

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

This example demonstrates how to use the Whisper API for multilingual transcription with speaker diarization enabled. It shows how to read an audio file, encode it in base64, and send a POST request to the transcription endpoint. The response includes detected language, processing time, and a detailed transcript with speaker information.

```APIDOC
## POST /v1/whisper/transcribe/base64 (Multilingual with Diarization)

### Description
This endpoint is used to transcribe audio files using the Whisper model, with support for multiple languages and speaker diarization. It takes base64 encoded audio and returns a structured JSON response containing the transcribed text, detected language, processing time, and word-level details including speaker identification.

### Method
POST

### Endpoint
https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64

### Parameters
#### Request Body
- **audio** (string) - Required - Base64 encoded audio data.
- **diarize** (boolean) - Optional - Set to `true` to enable speaker diarization. Defaults to `false`.
- **format** (string) - Optional - The format of the audio file (e.g., 'wav', 'mp3').

### Request Example
```json
{
  "audio": "BASE64_ENCODED_AUDIO_DATA",
  "diarize": true,
  "format": "wav"
}
```

### Response
#### Success Response (200)
- **text** (string) - The complete transcribed text.
- **words** (array) - An array of word objects, each containing:
  - **word** (string) - The transcribed word.
  - **start** (number) - The start time of the word in seconds.
  - **end** (number) - The end time of the word in seconds.
  - **speaker** (string) - The identified speaker (e.g., 'SPEAKER_00', 'SPEAKER_01') if `diarize` is true.
- **metadata** (object) - Contains metadata about the transcription:
  - **language** (string) - The detected language of the audio.
  - **processingTimeMs** (number) - The time taken for processing in milliseconds.

#### Response Example
```json
{
  "text": "Hello everyone, welcome to our meeting.",
  "words": [
    {"word": "Hello", "start": 0.4, "end": 0.8, "speaker": "SPEAKER_00"},
    {"word": "everyone,", "start": 0.9, "end": 1.5, "speaker": "SPEAKER_00"},
    {"word": "welcome", "start": 1.6, "end": 2.1, "speaker": "SPEAKER_00"},
    {"word": "to", "start": 2.2, "end": 2.3, "speaker": "SPEAKER_00"},
    {"word": "our", "start": 2.4, "end": 2.6, "speaker": "SPEAKER_00"},
    {"word": "meeting.", "start": 2.7, "end": 3.2, "speaker": "SPEAKER_00"}
  ],
  "metadata": {
    "language": "en",
    "processingTimeMs": 2150
  }
}
```
```

--------------------------------

### JavaScript: Express.js Transcription Service

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

This section provides an example of an Express.js service that acts as a transcription API endpoint, accepting audio files and using either the Whisper or Compact STT engine.

```APIDOC
## POST /api/transcribe

### Description
An Express.js endpoint that accepts audio file uploads and transcribes them using either the Whisper or Compact STT engine.

### Method
POST

### Endpoint
/api/transcribe

### Parameters
#### Query Parameters
- **engine** (string) - Optional - The STT engine to use ('whisper' or 'compact'). Defaults to 'whisper'.
- **diarize** (boolean) - Optional - Whether to perform speaker diarization (only applicable for Whisper engine). Accepts 'true' or 'false'.
- **language** (string) - Optional - The language of the audio (only applicable for Whisper engine).

#### Request Body
- **audio** (file) - Required - The audio file to transcribe (multipart/form-data).

### Request Example
(Using curl for demonstration)
```bash
curl -X POST http://localhost:3001/api/transcribe \
  -F "audio=@audio.wav" \
  -F "engine=whisper" \
  -F "language=en" \
  -F "diarize=true"
```

### Response
#### Success Response (200)
- **engine** (string) - The STT engine used.
- **filename** (string) - The original name of the uploaded audio file.
- **text** (string) - The transcribed text.
- **metadata** (object) - Metadata about the transcription.
- **words** (array) - An array of word objects (if applicable).

#### Response Example
```json
{
  "engine": "whisper",
  "filename": "audio.wav",
  "text": "This is the transcribed text.",
  "metadata": {
    "language": "en"
  }
}
```

#### Error Response (400, 500)
- **error** (string) - Description of the error.
```

--------------------------------

### GET /v1/stt/health

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Checks the health status of the compact STT engine.

```APIDOC
## GET /v1/stt/health

### Description
Checks the health status of the compact STT engine.

### Method
GET

### Endpoint
`https://apim-ai-apis.azure-api.net/v1/stt/health`

### Parameters
None

### Response
#### Success Response (200)
Typically returns a status indicating the engine is healthy (e.g., `{"status": "ok"}`).

```

--------------------------------

### Migrate AssemblyAI to Brainiall Whisper (Python)

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Compares transcription code and features for AssemblyAI versus Brainiall Whisper. Shows how to transcribe audio with speaker labels using both services, illustrating the migration to Brainiall Whisper for potential cost savings.

```python
# BEFORE: AssemblyAI ($0.0025/min)
import assemblyai as aai
aai.settings.api_key = "YOUR_ASSEMBLYAI_KEY"
transcriber = aai.Transcriber()
config = aai.TranscriptionConfig(speaker_labels=True, language_code="en")
transcript = transcriber.transcribe("audio.wav", config=config)
text = transcript.text

# AFTER: Brainiall Whisper ($0.006/min, or Compact $0.002/min for English-only)
import requests, base64

with open("audio.wav", "rb") as f:
    audio_b64 = base64.b64encode(f.read()).decode()
response = requests.post(
    "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64",
    headers={"Ocp-Apim-Subscription-Key": "YOUR_KEY", "Content-Type": "application/json"},
    json={"audio": audio_b64, "diarize": True},
)
text = response.json()["text"]

```

--------------------------------

### GET /v1/whisper/health

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Checks the health status of the Whisper Pro service. This endpoint is useful for verifying that the service is operational.

```APIDOC
## GET /v1/whisper/health

### Description
Whisper Pro health check.

### Method
GET

### Endpoint
/v1/whisper/health

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status of the service (e.g., "ok").

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### Migrate Google Cloud STT to Brainiall Whisper (Python)

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Compares transcription costs and code for Google Cloud Speech-to-Text versus Brainiall Whisper. Demonstrates how to transcribe an audio file using both services, highlighting the simpler and more cost-effective approach with Brainiall Whisper.

```python
# BEFORE: Google Cloud STT ($0.016/min)
from google.cloud import speech_v1

client = speech_v1.SpeechClient()
with open("audio.wav", "rb") as f:
    audio = speech_v1.RecognitionAudio(content=f.read())
config = speech_v1.RecognitionConfig(
    encoding=speech_v1.RecognitionConfig.AudioEncoding.LINEAR16,
    sample_rate_hertz=16000,
    language_code="en-US",
    enable_word_time_offsets=True,
    enable_automatic_punctuation=True,
)
response = client.recognize(config=config, audio=audio)
text = " ".join(r.alternatives[0].transcript for r in response.results)

# AFTER: Brainiall Whisper ($0.006/min) — 2.7x cheaper
import requests, base64

with open("audio.wav", "rb") as f:
    audio_b64 = base64.b64encode(f.read()).decode()
response = requests.post(
    "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64",
    headers={"Ocp-Apim-Subscription-Key": "YOUR_KEY", "Content-Type": "application/json"},
    json={"audio": audio_b64, "language": "en"},
)
text = response.json()["text"]

```

--------------------------------

### Compact STT Health Check

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

This endpoint performs a health check for the compact STT engine. It is a simple GET request used to verify the availability and status of the service.

```http
GET /v1/stt/health HTTP/1.1
Host: apim-ai-apis.azure-api.net
```

--------------------------------

### Process Podcast Audio (Python)

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Processes podcast audio files by transcribing them, extracting speaker information, and calculating word count and processing time. It utilizes the 'requests' library and requires an API key.

```python
import requests
import base64
import json

API_KEY = "YOUR_KEY"

def process_podcast(audio_path: str) -> dict:
    """Process a podcast: transcribe, extract chapters, generate summary."""
    with open(audio_path, "rb") as f:
        audio_b64 = base64.b64encode(f.read()).decode()

    # Transcribe with speakers
    result = requests.post(
        "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64",
        headers={"Ocp-Apim-Subscription-Key": API_KEY, "Content-Type": "application/json"},
        json={"audio": audio_b64, "diarize": True},
    ).json()

    transcript = result.get("text", "")
    processing_time = result.get("metadata", {}).get("processingTimeMs", 0)

    return {
        "transcript": transcript,
        "word_count": len(transcript.split()),
        "processing_time_ms": processing_time,
        "speakers": list(set(w.get("speaker", "") for w in result.get("words", []) if w.get("speaker"))),
    }

info = process_podcast("episode_42.mp3")
print(f"Words: {info['word_count']}, Speakers: {info['speakers']}")

```

--------------------------------

### Python STT Client with Retry and Error Handling

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Implements a production-ready Speech-to-Text (STT) client in Python. It includes automatic engine selection ('compact' or 'whisper' based on file size and diarization needs), retry logic for network requests, and error handling. The client supports transcribing audio files and checking service health.

```python
import requests
import base64
import time
from pathlib import Path

class BrainiallSTT:
    """Production STT client with retry logic and automatic engine selection."""

    def __init__(self, api_key: str, max_retries: int = 3, timeout: float = 60.0):
        self.api_key = api_key
        self.headers = {"Ocp-Apim-Subscription-Key": api_key, "Content-Type": "application/json"}
        self.max_retries = max_retries
        self.timeout = timeout

    def transcribe(
        self,
        audio_path: str,
        engine: str = "auto",
        language: str | None = None,
        diarize: bool = False,
    ) -> dict:
        """Transcribe audio file. Engine: 'compact', 'whisper', or 'auto' (auto-selects based on file size)."""
        audio_bytes = Path(audio_path).read_bytes()

        if engine == "auto":
            # Use compact for small files (<500KB, likely short English), whisper for everything else
            engine = "compact" if len(audio_bytes) < 500_000 and not diarize else "whisper"

        audio_b64 = base64.b64encode(audio_bytes).decode()

        if engine == "whisper":
            url = "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64"
            payload = {"audio": audio_b64, "diarize": diarize}
            if language:
                payload["language"] = language
        else:
            url = "https://apim-ai-apis.azure-api.net/v1/stt/transcribe/base64"
            payload = {"audio": audio_b64, "include_timestamps": True}

        for attempt in range(self.max_retries):
            try:
                response = requests.post(
                    url, headers=self.headers, json=payload, timeout=self.timeout
                )
                response.raise_for_status()
                result = response.json()
                result["engine"] = engine
                return result
            except requests.exceptions.RequestException as e:
                if attempt < self.max_retries - 1:
                    wait = 2 ** attempt
                    print(f"Retry {attempt + 1}/{self.max_retries} after {wait}s: {e}")
                    time.sleep(wait)
                else:
                    raise

    def transcribe_meeting(self, audio_path: str, language: str = "en") -> dict:
        """Convenience method: transcribe meeting with speaker diarization."""
        return self.transcribe(audio_path, engine="whisper", language=language, diarize=True)

    def is_healthy(self, engine: str = "whisper") -> bool:
        """Check if the STT service is healthy."""
        url = f"https://apim-ai-apis.azure-api.net/v1/{'whisper' if engine == 'whisper' else 'stt'}/health"
        try:
            r = requests.get(url, headers=self.headers, timeout=5.0)
            return r.status_code == 200
        except Exception:
            return False

# Usage
stt = BrainiallSTT(api_key="YOUR_KEY")

# Auto-select engine
result = stt.transcribe("short_command.wav")  # Uses compact (small file)
print(f"Engine: {result['engine']}, Text: {result['text']}")

result = stt.transcribe("long_podcast.mp3")  # Uses whisper (large file)
print(f"Engine: {result['engine']}, Text: {result['text'][:100]}...")

# Meeting transcription with speakers
meeting = stt.transcribe_meeting("standup.wav")
current_speaker = None
for word in meeting.get("words", []):
    if word.get("speaker") != current_speaker:
        current_speaker = word.get("speaker")
        print(f"\n[{current_speaker}]: ", end="")
    print(word["word"], end=" ")

```

--------------------------------

### MCP Server Configuration for Brainiall

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

This JSON configuration defines the 'brainiall-speech' MCP server. It includes the API endpoint URL and necessary headers, such as the subscription key and accepted content types, for interacting with Brainiall's speech services.

```json
{
  "mcpServers": {
    "brainiall-speech": {
      "url": "https://apim-ai-apis.azure-api.net/mcp/pronunciation/mcp",
      "headers": {
        "Ocp-Apim-Subscription-Key": "YOUR_KEY",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}
```

--------------------------------

### Python: Async STT Transcription with httpx

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Enables asynchronous speech-to-text transcription using the 'httpx' library, supporting both compact and Whisper engines. It allows for optional language specification and diarization. The function can transcribe single files or batches concurrently. Requires 'httpx' and 'asyncio'.

```python
import httpx
import asyncio
import base64
from pathlib import Path

API_KEY = "YOUR_KEY"

async def transcribe_async(
    audio_path: str,
    engine: str = "whisper",
    language: str | None = None,
    diarize: bool = False,
    client: httpx.AsyncClient | None = None,
) -> dict:
    """Async transcription supporting both compact and whisper engines."""
    audio_b64 = base64.b64encode(Path(audio_path).read_bytes()).decode()

    if engine == "whisper":
        url = "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64"
        payload = {"audio": audio_b64, "diarize": diarize}
        if language:
            payload["language"] = language
    else:
        url = "https://apim-ai-apis.azure-api.net/v1/stt/transcribe/base64"
        payload = {"audio": audio_b64, "include_timestamps": True}

    _client = client or httpx.AsyncClient(timeout=60.0)
    try:
        response = await _client.post(
            url,
            headers={
                "Ocp-Apim-Subscription-Key": API_KEY,
                "Content-Type": "application/json",
            },
            json=payload,
        )
        response.raise_for_status()
        return response.json()
    finally:
        if client is None:
            await _client.aclose()

async def batch_transcribe(audio_files: list[str], engine: str = "whisper") -> list[dict]:
    """Transcribe multiple audio files concurrently."""
    async with httpx.AsyncClient(timeout=120.0) as client:
        tasks = [
            transcribe_async(path, engine=engine, client=client)
            for path in audio_files
        ]
        results = await asyncio.gather(*tasks, return_exceptions=True)

    output = []
    for path, result in zip(audio_files, results):
        if isinstance(result, Exception):
            output.append({"file": path, "error": str(result)})
        else:
            output.append({"file": path, **result})
    return output

# Usage
async def main():
    files = ["audio1.wav", "audio2.wav", "audio3.wav"]
    results = await batch_transcribe(files, engine="whisper")
    for r in results:
        if "error" in r:
            print(f"  ERROR {r['file']}: {r['error']}")
        else:
            print(f"  {r['file']}: {r['text'][:80]}...")

asyncio.run(main())
```

--------------------------------

### Transcribe Audio using Base64 (Compact STT)

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

This endpoint utilizes the compact STT engine for transcribing base64-encoded audio. It supports inclusion of word-level timestamps and accepts common audio formats. This is ideal for short English utterances and real-time transcription.

```json
{
  "audio": "<base64-encoded WAV/MP3/FLAC/OGG>",
  "include_timestamps": true,
  "format": "wav"
}
```

--------------------------------

### Transcribe Audio using Multipart Form-Data (Compact STT)

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

This endpoint provides a multipart form-data alternative for the compact STT engine. It allows uploading audio files directly and optionally includes word-level timestamps.

```http
POST /v1/stt/transcribe HTTP/1.1
Host: apim-ai-apis.azure-api.net
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data;

name="audio"

<audio file data>
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data;

name="include_timestamps"

true
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

--------------------------------

### Batch Transcription Pipeline

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Utility function to process multiple audio files in a directory for transcription using a thread pool.

```APIDOC
## Batch Transcription Pipeline

### Description
This section describes a Python utility for batch transcribing audio files located in a specified directory. It leverages threading for concurrent processing and sends audio data via base64 encoding to the Whisper transcription endpoint.

### Method
N/A (This is a client-side script)

### Endpoint
(Internal processing, calls /v1/whisper/transcribe/base64)

### Parameters
(Refer to the `transcribe_file` function and its usage in the provided Python script)

### Request Example
(See Python code example in the original prompt for request structure)

### Response
(The script aggregates results from individual file transcriptions. Each result is a dictionary containing the filename and the transcription result.)

#### Response Example
```json
{
  "file": "audio1.wav",
  "result": {
    "text": "Transcription for audio1."
  }
}
```
```

--------------------------------

### Analyze Support Call with Speaker ID and LLM (Python)

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Transcribes customer support calls using speaker identification and then analyzes the transcript with an LLM to extract sentiment, topics, resolution status, satisfaction score, and action items. Requires the 'requests' and 'openai' libraries, and an API key.

```python
import requests
import base64
from openai import OpenAI

API_KEY = "YOUR_KEY"

def analyze_support_call(audio_path: str) -> dict:
    """Transcribe and analyze a customer support call."""
    with open(audio_path, "rb") as f:
        audio_b64 = base64.b64encode(f.read()).decode()

    # Transcribe with diarization
    stt = requests.post(
        "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64",
        headers={"Ocp-Apim-Subscription-Key": API_KEY, "Content-Type": "application/json"},
        json={"audio": audio_b64, "diarize": True, "language": "en"},
    ).json()

    # Build speaker-labeled transcript
    lines, current_speaker, words = [], None, []
    for w in stt.get("words", []):
        if w.get("speaker") != current_speaker:
            if words:
                lines.append(f"[{current_speaker}]: {' '.join(words)}")
            current_speaker = w.get("speaker")
            words = [w["word"]]
        else:
            words.append(w["word"])
    if words:
        lines.append(f"[{current_speaker}]: {' '.join(words)}")
    transcript = "\n".join(lines)

    # Analyze with LLM
    client = OpenAI(base_url="https://apim-ai-apis.azure-api.net/v1", api_key=API_KEY)
    analysis = client.chat.completions.create(
        model="claude-haiku-4-5",
        messages=[
            {"role": "system", "content": "Analyze this support call. Return JSON with: sentiment (positive/negative/neutral), topics (list), resolution (resolved/unresolved), satisfaction_score (1-10), action_items (list)."},
            {"role": "user", "content": transcript},
        ],
        response_format={"type": "json_object"},
    )

    return {"transcript": transcript, "analysis": analysis.choices[0].message.content}

```

--------------------------------

### Python Multipart File Upload for Whisper Transcription

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Demonstrates how to transcribe an audio file using the Whisper API via a direct multipart file upload. This method avoids base64 encoding the audio content, making it suitable for direct file transfers. It specifies the audio file, API key, and optional parameters like language and diarization.

```python
import requests

API_KEY = "YOUR_KEY"

# Upload audio file directly (no base64 encoding needed)
with open("podcast.mp3", "rb") as f:
    response = requests.post(
        "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe",
        headers={"Ocp-Apim-Subscription-Key": API_KEY},
        files={"audio": ("podcast.mp3", f, "audio/mpeg")},
        data={"language": "en", "diarize": "true"}
    )

result = response.json()
print(result["text"])

```

--------------------------------

### Generate Meeting Minutes from Audio using Python (STT + LLM)

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

This script first transcribes an audio recording with speaker diarization using the Whisper API. It then formats the transcript to include speaker labels and feeds it into an LLM (Claude Sonnet) via the OpenAI client to generate structured meeting minutes, including key points, decisions, and action items. Requires 'requests', 'base64', and 'openai' libraries.

```python
import requests
import base64
from openai import OpenAI

API_KEY = "YOUR_KEY"

# Step 1: Transcribe meeting with speaker diarization
with open("meeting_recording.wav", "rb") as f:
    audio_b64 = base64.b64encode(f.read()).decode()

stt_response = requests.post(
    "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64",
    headers={"Ocp-Apim-Subscription-Key": API_KEY, "Content-Type": "application/json"},
    json={"audio": audio_b64, "diarize": True, "language": "en"},
)
result = stt_response.json()

# Format transcript with speakers
transcript_lines = []
current_speaker = None
current_text = []
for word in result.get("words", []):
    speaker = word.get("speaker", "UNKNOWN")
    if speaker != current_speaker:
        if current_text:
            transcript_lines.append(f"[{current_speaker}]: {' '.join(current_text)}")
        current_speaker = speaker
        current_text = [word["word"]]
    else:
        current_text.append(word["word"])
if current_text:
    transcript_lines.append(f"[{current_speaker}]: {' '.join(current_text)}")

transcript = "\n".join(transcript_lines)

# Step 2: Generate meeting minutes with LLM
client = OpenAI(
    base_url="https://apim-ai-apis.azure-api.net/v1",
    api_key=API_KEY,
)

minutes = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {
            "role": "system",
            "content": "You are an expert meeting summarizer. Generate structured meeting minutes with: 1) Key Discussion Points, 2) Decisions Made, 3) Action Items (with owners if identifiable), 4) Next Steps.",
        },
        {"role": "user", "content": f"Generate meeting minutes from this transcript:\n\n{transcript}"},
    ],
)

print("=== Meeting Minutes ===")
print(minutes.choices[0].message.content)
```

--------------------------------

### Transcribe WAV Files in Directory (Python)

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

This Python script transcribes all WAV files within a specified directory using multithreading for efficiency. It utilizes the `ThreadPoolExecutor` to process files in parallel and prints the transcription results, truncating long texts.

```python
from pathlib import Path
from concurrent.futures import ThreadPoolExecutor

audio_dir = Path("recordings")
audio_files = list(audio_dir.glob("*.wav"))

print(f"Transcribing {len(audio_files)} files...")

with ThreadPoolExecutor(max_workers=5) as pool:
    results = list(pool.map(transcribe_file, audio_files))

for item in results:
    text = item["result"].get("text", "ERROR")
    print(f"  {item['file']}: {text[:80]}...")
```

--------------------------------

### Generate SRT Subtitles from Audio using Python

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

This script takes an audio file, transcribes it using the Whisper model via a REST API, and generates SRT subtitle entries. It formats the timestamps and groups words into lines based on a specified maximum word count per line. Requires the 'requests' and 'base64' libraries.

```python
import requests
import base64

API_KEY = "YOUR_KEY"
HEADERS = {"Ocp-Apim-Subscription-Key": API_KEY, "Content-Type": "application/json"}

def format_srt_time(seconds: float) -> str:
    """Convert seconds to SRT time format HH:MM:SS,mmm."""
    h = int(seconds // 3600)
    m = int((seconds % 3600) // 60)
    s = int(seconds % 60)
    ms = int((seconds % 1) * 1000)
    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"

def generate_srt(audio_path: str, max_words_per_line: int = 8) -> str:
    """Generate SRT subtitle file from audio using Whisper."""
    with open(audio_path, "rb") as f:
        audio_b64 = base64.b64encode(f.read()).decode()

    response = requests.post(
        "https://apim-ai-apis.azure-api.net/v1/whisper/transcribe/base64",
        headers=HEADERS,
        json={"audio": audio_b64, "language": "en"},
    )
    result = response.json()
    words = result.get("words", [])

    srt_entries = []
    entry_num = 1
    i = 0
    while i < len(words):
        chunk = words[i : i + max_words_per_line]
        start = chunk[0]["start"]
        end = chunk[-1]["end"]
        text = " ".join(w["word"] for w in chunk)

        srt_entries.append(
            f"{entry_num}\n{format_srt_time(start)} --> {format_srt_time(end)}\n{text}\n"
        )
        entry_num += 1
        i += max_words_per_line

    return "\n".join(srt_entries)

# Usage
srt_content = generate_srt("video_audio.wav", max_words_per_line=10)
with open("subtitles.srt", "w") as f:
    f.write(srt_content)
print("Subtitles generated!")
print(srt_content[:500])
```

--------------------------------

### POST /v1/stt/transcribe/base64

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Transcribes audio data using the compact STT engine. This engine is optimized for short English utterances and provides low latency.

```APIDOC
## POST /v1/stt/transcribe/base64

### Description
Transcribes audio data using the compact STT engine. This engine is optimized for short English utterances and provides low latency.

### Method
POST

### Endpoint
`https://apim-ai-apis.azure-api.net/v1/stt/transcribe/base64`

### Parameters
#### Request Body
- **audio** (string) - Required - Base64-encoded audio data. Supported formats: WAV, MP3, FLAC, OGG.
- **include_timestamps** (boolean) - Optional - Include word-level timestamps. Default: `true`.
- **format** (string) - Optional - Audio format hint. Default: `wav`. Supported: `wav`, `mp3`, `flac`, `ogg`.

### Request Example
```json
{
  "audio": "<base64-encoded WAV/MP3/FLAC/OGG>",
  "include_timestamps": true,
  "format": "wav"
}
```

### Response
#### Success Response (200)
- **text** (string) - The transcribed text.
- **words** (array) - An array of word objects, each containing `word`, `start` time, `end` time, and `confidence`.
- **audioDurationMs** (integer) - The duration of the audio in milliseconds.

#### Response Example
```json
{
  "text": "hello world how are you",
  "words": [
    {"word": "hello", "start": 0.12, "end": 0.45, "confidence": 0.98},
    {"word": "world", "start": 0.52, "end": 0.89, "confidence": 0.97},
    {"word": "how", "start": 0.95, "end": 1.12, "confidence": 0.99},
    {"word": "are", "start": 1.15, "end": 1.28, "confidence": 0.98},
    {"word": "you", "start": 1.30, "end": 1.52, "confidence": 0.97}
  ],
  "audioDurationMs": 1800
}
```
```

--------------------------------

### POST /v1/stt/transcribe/base64

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Transcribes audio data provided in Base64 format using the compact STT engine. It supports including timestamps for each word.

```APIDOC
## POST /v1/stt/transcribe/base64

### Description
Transcribes audio data provided in Base64 format using the compact STT engine. It supports including timestamps for each word.

### Method
POST

### Endpoint
/v1/stt/transcribe/base64

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **audio** (string) - Required - Base64 encoded audio data.
- **include_timestamps** (boolean) - Optional - If true, includes timestamps for each word in the response.

### Request Example
```json
{
  "audio": "BASE64_ENCODED_AUDIO_DATA",
  "include_timestamps": true
}
```

### Response
#### Success Response (200)
- **text** (string) - The transcribed text.
- **audioDurationMs** (integer) - The duration of the audio in milliseconds.
- **words** (array) - An array of word objects, each containing start time, end time, the word itself, and confidence score (if `include_timestamps` is true).
  - **start** (float) - The start time of the word in seconds.
  - **end** (float) - The end time of the word in seconds.
  - **word** (string) - The transcribed word.
  - **confidence** (float) - The confidence score for the word transcription.

#### Response Example
```json
{
  "text": "Hello world, this is a test.",
  "audioDurationMs": 5000,
  "words": [
    {"start": 0.50, "end": 1.20, "word": "Hello", "confidence": 0.95},
    {"start": 1.30, "end": 1.80, "word": "world", "confidence": 0.98},
    {"start": 2.00, "end": 2.50, "word": "this", "confidence": 0.92},
    {"start": 2.60, "end": 2.90, "word": "is", "confidence": 0.90},
    {"start": 3.00, "end": 3.30, "word": "a", "confidence": 0.88},
    {"start": 3.40, "end": 4.00, "word": "test", "confidence": 0.96}
  ]
}
```
```

--------------------------------

### Python: Basic STT Transcription

Source: https://raw.githubusercontent.com/fasuizu-br/speech-ai-examples/main/stt-llms-full.txt

Performs basic speech-to-text transcription using a provided API key and audio file. It reads an audio file, encodes it to base64, sends it to the transcription endpoint, and prints the transcribed text, audio duration, and word-level timestamps with confidence scores. Requires the 'requests' library.

```python
import requests
import base64

API_KEY = "YOUR_KEY"
HEADERS = {"Ocp-Apim-Subscription-Key": API_KEY, "Content-Type": "application/json"}

# Read and encode audio
with open("recording.wav", "rb") as f:
    audio_b64 = base64.b64encode(f.read()).decode()

# Transcribe
response = requests.post(
    "https://apim-ai-apis.azure-api.net/v1/stt/transcribe/base64",
    headers=HEADERS,
    json={"audio": audio_b64, "include_timestamps": True}
)

result = response.json()
print(f"Text: {result['text']}")
print(f"Duration: {result['audioDurationMs']}ms")
for word in result["words"]:
    print(f"  [{word['start']:.2f}-{word['end']:.2f}] {word['word']} ({word['confidence']:.0%})")
```