# Input

Learn about configuration and supported input audio formats for the Speechmatics Batch API

## Supported file types[​](#supported-file-types "Direct link to Supported file types")

The following file formats types are supported for transcription by REST API:

* `wav`
* `mp3`
* `aac`
* `ogg`
* `mpeg`
* `amr`
* `m4a`
* `mp4`
* `flac`

The list above is exhaustive - any file format outside the list above is explicitly not supported.

Only files where the type can be determined by data inspection are supported. Raw audio formats where the codec is not embedded in the file cannot be processed in batch mode. This includes files commonly given extensions like ".raw" or ".g729" where the codec is only hinted at in the name.

The optimal format for speed is 16bit 16kHz mono WAV. This format will not need preprocessing before transcription, which can make a difference to turnaround time for very short input files.

## Job configuration options[​](#job-configuration-options "Direct link to Job configuration options")

Jobs are configured by passing a JSON string to the `config` field of the `CreateJobRequest` (see [API reference](/api-ref/batch/create-a-new-job.md))

### `JobConfig` schema[​](#jobconfig-schema "Direct link to jobconfig-schema")

Below are the complete fields of the configuration object:

`JobConfig`In the API reference: [Create a new job](/api-ref/batch/create-a-new-job.md)

* * `type`

    `JobType`"transcription"
  * `fetch_data`

    `DataFetchConfig`

    optional
  * `fetch_text`

    `DataFetchConfig`

    optional
  * `transcription_config`

    `TranscriptionConfig`

    optional
  * `notification_config`

    `NotificationConfig[]`

    optional
  * `tracking`

    `TrackingData`

    optional
  * `output_config`

    `OutputConfig`

    optional
  * `translation_config`

    `TranslationConfig`

    optional
  * `language_identification_config`

    `LanguageIdentificationConfig`

    optional
  * `summarization_config`

    `SummarizationConfig`

    optional
  * `sentiment_analysis_config`

    `SentimentAnalysisConfig`

    optional
  * `topic_detection_config`

    `TopicDetectionConfig`

    optional
  * `auto_chapters_config`

    `AutoChaptersConfig`

    optional
  * `audio_events_config`

    `AudioEventsConfig`

    optional

  - ▸Show 2 properties

  - `url`

    `string`

  - `auth_headers`

    `string[]`

    optional

  - A list of additional headers to be added to the input fetch request when using http or https. This is intended to support authentication or authorization, for example by supplying an OAuth2 bearer token.

  - ▸Show 2 properties

  - `url`

    `string`

  - `auth_headers`

    `string[]`

    optional

  - A list of additional headers to be added to the input fetch request when using http or https. This is intended to support authentication or authorization, for example by supplying an OAuth2 bearer token.

  - ▸Show 14 properties

  - `language`

    `string`

  - Language model to process the audio input, normally specified as an ISO language code

  - `domain`

    `string`

    optional

  - Request a specialized model based on 'language' but optimized for a particular field, e.g. 'finance' or 'medical'.

  - `output_locale`

    `string`

    optional

  - Language locale to be used when generating the transcription output, normally specified as an ISO language code

  - `model`

    `Model`"standard""enhanced""melia-1"

    optional

  - Specific model to use in transcription (previously called operating point).

  - `operating_point`

    `OperatingPoint`"standard""enhanced""melia-1"

    optional

  - `additional_vocab`

    `object[]`≤ 20000 items

    optional

  - List of custom words or phrases that should be recognized. Alternative pronunciations can be specified to aid recognition.

    ▸Show 2 properties

  - `transcription_config.additional_vocab[].``content`

    `string`

  - `transcription_config.additional_vocab[].``sounds_like`

    `string[]`

    optional

  - `punctuation_overrides`

    `object`

    optional

  - Control punctuation settings.

    ▸Show 2 properties

  - `transcription_config.punctuation_overrides.``sensitivity`

    `number<float>`≥ 0, ≤ 1

    optional

  - Ranges between zero and one. Higher values will produce more punctuation. The default is 0.5.

  - `transcription_config.punctuation_overrides.``permitted_marks`

    `string[]`

    optional

  - The punctuation marks which the client is prepared to accept in transcription output, or the special value 'all' (the default). Unsupported marks are ignored. This value is used to guide the transcription process.

  - `diarization`

    `"none" | "speaker" | "channel"`

    optional

  - Specify whether speaker or channel labels are added to the transcript. The default is `none`.

    * **none**: no speaker or channel labels are added.
    * **speaker**: speaker attribution is performed based on acoustic matching; all input channels are mixed into a single stream for processing.
    * **channel**: multiple input channels are processed individually and collated into a single transcript.

  - `channel_diarization_labels`

    `string[]`

    optional

  - Transcript labels to use when using collating separate input channels.

  - `enable_entities`

    `boolean`

    optional

  - Include additional 'entity' objects in the transcription results (e.g. dates, numbers) and their original spoken form. These entities are interleaved with other types of results. The concatenation of these words is represented as a single entity with the concatenated written form present in the 'content' field. The entities contain a 'spoken\_form' field, which can be used in place of the corresponding 'word' type results, in case a spoken form is preferred to a written form. They also contain a 'written\_form', which can be used instead of the entity, if you want a breakdown of the words without spaces. They can still contain non-breaking spaces and other special whitespace characters, as they are considered part of the word for the formatting output. In case of a written\_form, the individual word times are estimated and might not be accurate if the order of the words in the written form does not correspond to the order they were actually spoken (such as 'one hundred million dollars' and '$100 million').

  - `max_delay_mode`

    `"fixed" | "flexible"`

    optional

  - Whether or not to enable flexible endpointing and allow the entity to continue to be spoken.

  - `audio_filtering_config`

    `object`

    optional

  - Configuration for limiting the transcription of quiet audio.

    ▸Show 1 property

  - `transcription_config.audio_filtering_config.``volume_threshold`

    `number<float>`≥ 0, ≤ 100

    optional

  - Controls the lower limit of audio volume at which speech and audio events will be transcribed. If the volume limit is very low, then most sound will be passed to the speech recognition engine. Higher numbers will cut out increasing amounts of sound.

  - `transcript_filtering_config`

    `object`

    optional

  - Configuration for applying filtering to the transcription

    ▸Show 2 properties

  - `transcription_config.transcript_filtering_config.``remove_disfluencies`

    `boolean`

    optional

  - If true, words that are identified as disfluencies will be removed from the transcript. If false (default), they are tagged in the transcript as 'disfluency'.

  - `transcription_config.transcript_filtering_config.``replacements`

    `object[]`

    optional

  - An array of objects defining custom replacements. Each replacement contains a pair of strings: the text to find `from` and the text to replace it with `to`.

    ▸Show 2 properties

  - `transcription_config.transcript_filtering_config.replacements[].``from`

    `string`

  - `transcription_config.transcript_filtering_config.replacements[].``to`

    `string`

  - `speaker_diarization_config`

    `object`

    optional

  - Configuration for speaker diarization

    ▸Show 4 properties

  - `transcription_config.speaker_diarization_config.``prefer_current_speaker`

    `boolean`

    optional

  - If true, the algorithm will prefer to stay with the current active speaker if it is a close enough match, even if other speakers may be closer. This is useful for cases where we can flip incorrectly between similar speakers during a single speaker section.

  - `transcription_config.speaker_diarization_config.``speaker_sensitivity`

    `number<float>`≥ 0, ≤ 1

    optional

  - Controls how sensitive the algorithm is in terms of keeping similar speakers separate, as opposed to combining them into a single speaker. Higher values will typically lead to more speakers, as the degree of difference between speakers in order to allow them to remain distinct will be lower. A lower value for this parameter will conversely guide the algorithm towards being less sensitive in terms of retaining similar speakers, and as such may lead to fewer speakers overall. The default is 0.5.

  - `transcription_config.speaker_diarization_config.``get_speakers`

    `boolean`

    optional

  - If true, speaker identifiers will be returned at the end of transcript.

  - `transcription_config.speaker_diarization_config.``speakers`

    `SpeakersInputItem[]`

    optional

  - Use this option to provide speaker labels linked to their speaker identifiers. When passed, the transcription system will tag spoken words in the transcript with the provided speaker labels whenever any of the specified speakers is detected in the audio. A maximum of 50 speakers identifiers across all speakers can be provided.

    ▸Show 2 properties

  - `transcription_config.speaker_diarization_config.speakers[].``label`

    `string`≥ 1 characters

  - Speaker label, which must not match the format used internally (e.g. S1, S2, etc)

  - `transcription_config.speaker_diarization_config.speakers[].``speaker_identifiers`

    `Array<string<bytes>>`≥ 1 itemsunique items

  - ▸Show 4 properties

  - `url`

    `string`

  - The url to which a notification message will be sent upon completion of the job. The job `id` and `status` are added as query parameters, and any combination of the job inputs and outputs can be included by listing them in `contents`.

    If `contents` is empty, the body of the request will be empty.

    If only one item is listed, it will be sent as the body of the request with `Content-Type` set to an appropriate value such as `application/octet-stream` or `application/json`.

    If multiple items are listed they will be sent as named file attachments using the multipart content type.

    If `contents` is not specified, the `transcript` item will be sent as a file attachment named `data_file`, for backwards compatibility.

    If the job was rejected or failed during processing, that will be indicated by the status, and any output items that are not available as a result will be omitted. The body formatting rules will still be followed as if all items were available.

    The user-agent header is set to `Speechmatics-API/2.0`, or `Speechmatics API V2` in older API versions.

  - `contents`

    `enum[]`

    optional

  - Specifies a list of items to be attached to the notification message. When multiple items are requested, they are included as named file attachments.

  - `method`

    `"post" | "put"`

    optional

  - The method to be used with http and https urls. The default is post.

  - `auth_headers`

    `string[]`

    optional

  - A list of additional headers to be added to the notification request when using http or https. This is intended to support authentication or authorization, for example by supplying an OAuth2 bearer token.

  - ▸Show 4 properties

  - `title`

    `string`

    optional

  - The title of the job.

  - `reference`

    `string`

    optional

  - External system reference.

  - `tags`

    `string[]`

    optional

  - `details`

    `object`

    optional

  - Customer-defined JSON structure.

  - ▸Show 1 property

  - `srt_overrides`

    `object`

    optional

  - Parameters that override default values of srt conversion. max\_line\_length: sets maximum count of characters per subtitle line including white space. max\_lines: sets maximum count of lines in a subtitle section.

    ▸Show 2 properties

  - `output_config.srt_overrides.``max_line_length`

    `integer`

    optional

  - `output_config.srt_overrides.``max_lines`

    `integer`

    optional

  - ▸Show 1 property

  - `target_languages`

    `string[]`≤ 5 items

  - ▸Show 3 properties

  - `expected_languages`

    `string[]`

    optional

  - `low_confidence_action`

    `"allow" | "reject" | "use_default_language"`

    optional

  - Action to take if all of the predicted languages are below the confidence threshold

  - `default_language`

    `string`

    optional

  - Configuration options for summarization.

    ▸Show 3 properties

  - `content_type`

    `"auto" | "informative" | "conversational"`

    optional

  - Choose from three options:

    * `conversational` - Best suited for dialogues involving multiple participants, such as calls, meetings or discussions. It focuses on summarizing key points of the conversation.
    * `informative` - Recommended for more structured information delivered by one or more people, making it ideal for videos, podcasts, lectures, and presentations.
    * `auto` - Automatically selects the most appropriate content type based on an analysis of the transcript.

  - `summary_length`

    `"brief" | "detailed"`default: "brief"

    optional

  - Determines the depth of the summary:

    * `brief` - Provides a succinct summary, condensing the content into just a few sentences.
    * `detailed` - Provide a longer, structured summary. For *conversational* content, it includes key topics and a summary of the entire conversation. For *informative* content, it logically divides the audio into sections and provides a summary for each.

  - `summary_type`

    `"paragraphs" | "bullets"`

    optional

  - ▸Show 1 property

  - `topics`

    `string[]`

    optional

  - ▸Show 1 property

  - `types`

    `string[]`

    optional

### Language hints[​](#language-hints "Direct link to Language hints")

The Melia 1 model detects every language it hears automatically, so language hints are optional. To select Melia 1, refer to [Models](/speech-to-text/models.md).

Hints tell the model which languages to expect in the audio, biasing detection toward them. They are most useful for short clips, audio with heavy accents, or recordings where two languages sound similar, where they make language labeling more reliable.

Provide hints as a list of [supported languages](/speech-to-text/languages.md#transcription-languages) to guide detection without restricting it. This config hints that the audio contains English and Arabic:

```
{
  "type": "transcription",
  "transcription_config": {
    "model": "melia-1",
    "language": "multi",
    "language_hints": ["en", "ar"]
  }
}
```

The model can still detect and label a language you did not hint, and it labels only the languages it actually hears.

## Fetch URL[​](#fetch-url "Direct link to Fetch URL")

If you store your digital media in cloud storage (for example AWS S3 or Azure Blob Storage) you can also submit a job by providing the URL of the audio file. The configuration uses a `fetch_data` section, which looks like this:

#### Configuration example[​](#configuration-example "Direct link to Configuration example")

```
{
  "type": "transcription",
  "transcription_config": {
    "model": "enhanced",
    "language": "en"
  },
  "fetch_data": {
    "url": "${URL}/{FILENAME}"
  }
}
```

In SaaS, fetch requests made to the URL in `fetch_data` have user agent set to `Speechmatics-API/2.0`.

#### Fetch failure[​](#fetch-failure "Direct link to Fetch failure")

If the Speechmatics Batch SaaS is unable to retrieve audio from the specified online location, the job will fail, with a `status` of `rejected`, and no transcript will be generated. Users can now retrieve failure information by making a GET /jobs/$JOBID request, and use that to carry out diagnostic information.

If the job has failed, there will be an additional `errors` element, which will show all failure messages Speechmatics Batch SaaS encountered when carrying out the fetch request. Please note, there can be multiple failure attempts associated with one submitted job, as there is a retry mechanism in place.

```
{
  "job": {
    "config": {
      "fetch_data": {
        "url": "https://example.com/average-files/punctuation1.mp3"
      },
      "notification_config": [
        {
          "contents": ["jobinfo"],
          "url": "https://example.com/"
        }
      ],
      "transcription_config": {
        "language": "de"
      },
      "type": "transcription"
    },
    "created_at": "2021-07-19T12:55:03.754Z",
    "data_name": "",
    "duration": 0,
    "errors": [
      {
        "message": "unable to fetch audio: http status code 404",
        "timestamp": "2021-07-19T12:55:05.425Z"
      },
      {
        "message": "unable to fetch audio: http status code 404",
        "timestamp": "2021-07-19T12:55:07.649Z"
      },
      {
        "message": "unable to fetch audio: http status code 404",
        "timestamp": "2021-07-19T12:55:17.665Z"
      },
      {
        "message": "unable to fetch audio: http status code 404",
        "timestamp": "2021-07-19T12:55:37.643Z"
      }
    ],
    "id": "a81ko4eqjl",
    "status": "rejected"
  }
}
```