> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transcribe audio to text

> Transcribes audio input into text. Supports three modes:

## 1. File Upload (Non-Streaming)
Upload an audio file and receive the complete transcription in a single response.

**Request:**
- Content-Type: `multipart/form-data`
- Include `file`, `model`, `stream=false`

**Response:**
- Complete transcription text
- Detected language

## 2. File Upload (Streaming Results)
Upload an audio file and receive partial transcription results via WebSocket.

**Request:**
- Content-Type: `multipart/form-data`
- Include `file`, `model`, `stream=true`

**Response:**
- Initial acknowledgment with `session_id`
- Partial results via WebSocket (`transcript.text.delta`)
- Final result via WebSocket (`transcript.text.done`)

## 3. Live Audio Streaming
Stream audio chunks in real-time via WebSocket.

**Request:**
- Content-Type: `application/json`
- Include `model`, `stream=true` (no file)

**Response:**
- Session ID for WebSocket connection
- Send audio chunks via WebSocket
- Receive events and partial results in real-time

## Event Sequence (Live Streaming with VAD)

When streaming live audio with VAD/EPD enabled, the server emits the
following sequence of WebSocket messages for each utterance:

1. **`transcript.event` / `speech_start`** — speech first detected by VAD
   ```json
   { "session_id": "session123", "type": "transcript.event", "state": "speech_start" }
   ```
2. **`transcript.text.delta`** — zero or more partial transcription results
   ```json
   { "session_id": "session123", "text": "Partial text...", "language": "en", "type": "transcript.text.delta", "state": "transcription" }
   ```
3. **`transcript.event` / `speech_end`** — end-of-speech detected by VAD/EPD
   ```json
   { "session_id": "session123", "type": "transcript.event", "state": "speech_end" }
   ```
4. **`transcript.text.done`** — final transcription for the utterance
   ```json
   { "session_id": "session123", "text": "Complete utterance text.", "language": "en", "type": "transcript.text.done", "state": "transcription" }
   ```

After step 4 the engine resets and listens for the next utterance.
The session remains open until the client calls `/transcriptions/close`.
The client may also call `/transcriptions/flush` at any time to force
immediate processing of buffered audio.

**Important - Session Timeout:**
When streaming audio, if no audio data is sent for a period of time (session timeout),
the session will automatically close and the final transcription will be sent. This
prevents sessions from remaining open indefinitely when audio streaming has stopped.

## Supported Audio Formats
- WAV (recommended)

## Sample Rates
- 16000 Hz (recommended)
- Automatic resampling available

## Parameters
You can include additional parameters for fine-tuning:
- `sampling_rate`: Target sample rate (e.g., "16000")
- `channels`: Number of audio channels (e.g., "1" for mono)




## OpenAPI

````yaml /Ubuntu/ai-workflows/api-specs/audio-analytics/openapi.yaml post /transcriptions/create
openapi: 3.0.3
info:
  title: Audio Analytics API
  version: 1.0.0
  description: >
    REST API providing AI-powered audio processing: speech recognition (ASR),

    text translation (T2T), and speech synthesis (TTS).


    ## Services


    | Service | Endpoint prefix | Description |

    |---------|----------------|-------------|

    | ASR | `/transcriptions/` | Whisper-based speech-to-text (file or live
    WebSocket streaming) |

    | T2T | `/translations/` | Opus/NLLB text translation (batch supported) |

    | TTS | `/tts/` | MeloTTS speech synthesis; returns raw PCM audio |


    ## Audio formats (ASR input)

    - WAV, 16-bit PCM; 16 kHz mono recommended; max 25 MB


    ## TTS output

    - Supported sample rates: 44100, 22050, 16000 Hz (auto-resampled)


    ## WebSocket streaming sequence


    ```

    App                                           Server
     |===POST /transcriptions/create================>|
     |<==200 {session_id, state: asr_initialized}====|
     |
     |===WS /stream=================================>|
     |<==  {state: connection_established}===========|
     |
     |===WS {transcriptions_session_audio} (loop)===>|
     |<===WS {transcript.event,     speech_start}====|
     |<===WS {transcript.text.delta, ...}============|  (zero or more)
     |<===WS {transcript.event,     speech_end}======|
     |<===WS {transcript.text.done,  ...}============|
     |
     |===POST /transcriptions/close=================>|  (after transcript.text.done)
    ```


    ## Authentication

    None required.
  contact:
    name: Qualcomm Support Forums
    url: https://mysupport.qualcomm.com/supportforums/s/
  license:
    name: BSD-3-Clause-Clear
    url: https://opensource.org/licenses/BSD-3-Clause-Clear
servers:
  - url: http://{device-ip}:{device-port}/audio-analytics/v1/api
    description: Audio Analytics API Server
    variables:
      device-ip:
        description: IP address and port of the host device running the Audio Analytics API
        default: localhost
      device-port:
        default: '8085'
security: []
tags:
  - name: Health
    description: Service health and status endpoints
  - name: Transcriptions
    description: Speech-to-text audio transcription (ASR)
  - name: Translations
    description: Text-to-text translation between languages
  - name: TTS
    description: Text-to-speech synthesis
  - name: WebSocket
    description: Real-time streaming communication
paths:
  /transcriptions/create:
    post:
      tags:
        - Transcriptions
      summary: Transcribe audio to text
      description: >
        Transcribes audio input into text. Supports three modes:


        ## 1. File Upload (Non-Streaming)

        Upload an audio file and receive the complete transcription in a single
        response.


        **Request:**

        - Content-Type: `multipart/form-data`

        - Include `file`, `model`, `stream=false`


        **Response:**

        - Complete transcription text

        - Detected language


        ## 2. File Upload (Streaming Results)

        Upload an audio file and receive partial transcription results via
        WebSocket.


        **Request:**

        - Content-Type: `multipart/form-data`

        - Include `file`, `model`, `stream=true`


        **Response:**

        - Initial acknowledgment with `session_id`

        - Partial results via WebSocket (`transcript.text.delta`)

        - Final result via WebSocket (`transcript.text.done`)


        ## 3. Live Audio Streaming

        Stream audio chunks in real-time via WebSocket.


        **Request:**

        - Content-Type: `application/json`

        - Include `model`, `stream=true` (no file)


        **Response:**

        - Session ID for WebSocket connection

        - Send audio chunks via WebSocket

        - Receive events and partial results in real-time


        ## Event Sequence (Live Streaming with VAD)


        When streaming live audio with VAD/EPD enabled, the server emits the

        following sequence of WebSocket messages for each utterance:


        1. **`transcript.event` / `speech_start`** — speech first detected by
        VAD
           ```json
           { "session_id": "session123", "type": "transcript.event", "state": "speech_start" }
           ```
        2. **`transcript.text.delta`** — zero or more partial transcription
        results
           ```json
           { "session_id": "session123", "text": "Partial text...", "language": "en", "type": "transcript.text.delta", "state": "transcription" }
           ```
        3. **`transcript.event` / `speech_end`** — end-of-speech detected by
        VAD/EPD
           ```json
           { "session_id": "session123", "type": "transcript.event", "state": "speech_end" }
           ```
        4. **`transcript.text.done`** — final transcription for the utterance
           ```json
           { "session_id": "session123", "text": "Complete utterance text.", "language": "en", "type": "transcript.text.done", "state": "transcription" }
           ```

        After step 4 the engine resets and listens for the next utterance.

        The session remains open until the client calls `/transcriptions/close`.

        The client may also call `/transcriptions/flush` at any time to force

        immediate processing of buffered audio.


        **Important - Session Timeout:**

        When streaming audio, if no audio data is sent for a period of time
        (session timeout),

        the session will automatically close and the final transcription will be
        sent. This

        prevents sessions from remaining open indefinitely when audio streaming
        has stopped.


        ## Supported Audio Formats

        - WAV (recommended)


        ## Sample Rates

        - 16000 Hz (recommended)

        - Automatic resampling available


        ## Parameters

        You can include additional parameters for fine-tuning:

        - `sampling_rate`: Target sample rate (e.g., "16000")

        - `channels`: Number of audio channels (e.g., "1" for mono)
      operationId: createTranscription
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateTranscriptionRequest'
            examples:
              file_sync:
                summary: File upload (non-streaming)
                value:
                  model: whisper-small-quantized
                  file: (binary audio data)
                  stream: false
                  language: en
                  parameters:
                    - key: sampling_rate
                      value: '16000'
                    - key: channels
                      value: '1'
              file_stream:
                summary: File upload (streaming results)
                value:
                  model: whisper-small-quantized
                  file: (binary audio data)
                  stream: true
                  language: en
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTranscriptionRequest'
            example:
              model: whisper-small-quantized
              stream: true
              language: en
      responses:
        '200':
          description: Transcription request accepted
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TranscriptionResponse'
                  - $ref: '#/components/schemas/TranscriptionSessionResponse'
              examples:
                non_streaming:
                  summary: Non-streaming response
                  value:
                    text: The transcribed text from the audio file.
                    language: en
                    type: transcript.text.done
                streaming:
                  summary: Streaming session created
                  value:
                    session_id: session123
        '400':
          description: Bad request - invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CreateTranscriptionRequest:
      type: object
      properties:
        model:
          type: string
          description: ID of the ASR model to use
          example: whisper-small-quantized
        file:
          type: string
          format: binary
          description: Audio file to transcribe (for file-based transcription)
        language:
          type: string
          description: >-
            ISO 639-1 language code (e.g., 'en' for English). If omitted,
            language may be auto-detected.
          example: en
        stream:
          oneOf:
            - type: string
            - type: boolean
          default: false
          description: >-
            If true, results will be streamed via WebSocket. If false, complete
            transcription returned in response.
          example: false
        channels:
          oneOf:
            - type: integer
            - type: string
              pattern: ^\d+$
          description: >-
            Number of audio channels in the input stream (1=mono, 2=stereo).
            Takes priority over the channels key inside the parameters array.
          example: 1
        parameters:
          description: >-
            Additional parameters for transcription (e.g., sampling_rate,
            channels)
          oneOf:
            - type: string
              description: JSON string of parameters (for multipart/form-data)
            - type: object
              additionalProperties: {}
              description: Object with parameters (for application/json)
            - type: array
              items:
                $ref: '#/components/schemas/KeyValueParam'
              description: Array of key-value pairs (for multipart/form-data)
          example: >-
            [{"key": "sampling_rate", "value": "16000"}, {"key": "channels",
            "value": "1"}, {"key": "server_timeout", "value": "60"}]
      required:
        - model
    TranscriptionResponse:
      type: object
      description: Transcription result (non-streaming)
      properties:
        text:
          type: string
          description: The transcribed text
          example: The sky is blue and the sun is shining.
        language:
          type: string
          description: Detected or specified language (ISO 639-1 code)
          example: en
        language_name:
          type: string
          description: Detected language full name as returned by the ASR engine
          example: English
        type:
          type: string
          description: Result type
          enum:
            - transcript.text.done
            - transcript.text.delta
          example: transcript.text.done
        session_id:
          type: string
          description: Session identifier (if applicable)
          example: session123
      required:
        - text
    TranscriptionSessionResponse:
      type: object
      description: Transcription session created (streaming)
      properties:
        session_id:
          type: string
          description: Unique session identifier for WebSocket connection
          example: session123
      required:
        - session_id
    ErrorResponse:
      type: object
      description: Standard error response structure
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message
              example: Invalid request, missing 'file' parameter
            type:
              type: string
              description: Error type or category
              example: invalid_request_error
            param:
              type: string
              nullable: true
              description: Parameter related to the error (if applicable)
              example: file
            code:
              type: string
              nullable: true
              description: Error code (if applicable)
              example: null
          required:
            - message
            - type
      required:
        - error
    KeyValueParam:
      type: object
      description: Key-value pair for additional parameters
      properties:
        key:
          type: string
          description: Parameter name
          example: sampling_rate
        value:
          type: string
          description: Parameter value
          example: '16000'
      required:
        - key
        - value

````