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

# Transcribe files, YouTube links and recordings

> Start a transcript from an audio or video file, several files at once, a YouTube link or your microphone, then follow its status and try a failed job again.

You start a transcript from the **Speech to text** page in one of three ways: upload files, paste a YouTube link, or record with your microphone. Each one asks for a title and the main language, then runs as a job in the background. This page covers the three ways, what happens next, and how to try again when a job fails.

## Before you start

* Credits left on the project owner's account. A job is refused when there are none. See [Credits](https://docs.tryhamsa.com/media/speech-to-text/overview.md#credits).
* A clear idea of the main language spoken: Arabic or English.

## Upload files

**1. Open the upload dialog**

In the sidebar, open **Speech to text** and click **Upload a file**. You can also drop files anywhere on the page ("Drop to transcribe"), or choose **Transcribe a file** on **Home**.

**2. Choose the files**

Drop them on "Drop files here, or choose them", or click **Choose files**. Add up to 10 files, each up to 200 MB. Click **Add files** to add more.

**3. Name and set the language**

With one file, check the **Title** (filled in from the file name) and pick the **Main language**: العربية (Arabic, the default) or English.

![The Transcribe a file dialog with one audio file chosen, its Title and the Main language set to العربية](https://mintcdn.com/hamsa-452fa79a/fdE-9_eEW1W6yh_s/images/media/speech-to-text/upload-file-dialog-light.webp?fit=max\&auto=format\&n=fdE-9_eEW1W6yh_s\&q=85\&s=82f7b587844110e0c9d53712feb05b14)

With several files, the dialog becomes **Transcribe files**. Each file becomes its own transcript, named after the file. Set **Language for all files**, or change the language of one file in its row.

**4. Start**

Click **Transcribe** (or **Transcribe 3 files**). "Transcription started." confirms it and the dialog closes.

![The Transcribe files dialog with four files: one Started, two uploading at 40% and 15%, and one Queued, with Language for all files set to العربية](https://mintcdn.com/hamsa-452fa79a/fdE-9_eEW1W6yh_s/images/media/speech-to-text/transcribe-files-batch-light.webp?fit=max\&auto=format\&n=fdE-9_eEW1W6yh_s\&q=85\&s=ff45c2f6fff6a54c5c41cd40219dc81b)

With several files, two upload at a time, and each row shows its own state: **Queued**, **Uploading 40%**, **Starting**, **Started**, **Failed** or **Stopped**. **Stop** halts the batch; files that failed or stopped can be sent again with **Retry**. For more on drag and drop and batches, see [Lists and uploads](https://docs.tryhamsa.com/media/workspace/lists-and-uploads.md).

### Supported files

| Format | Extension |
| - | - |
| MP3 audio | .mp3 |
| WAV audio | .wav |
| Ogg audio | .ogg |
| WebM audio or video | .webm |
| MP4 video | .mp4 |

A file of another type is turned away with "Upload an audio or video file.", and a file over 200 MB with "This file is over 200 MB. Upload a smaller one." When you add several files, the ones that weren't added are listed with the reason ("Not an audio or video file", "Over 200 MB", "Over the limit of 10 files").

![The Transcribe files dialog saying 1 file was not added: show-notes.pdf, Not an audio or video file, above the two audio files that were added](https://mintcdn.com/hamsa-452fa79a/fdE-9_eEW1W6yh_s/images/media/speech-to-text/transcribe-files-rejected-light.webp?fit=max\&auto=format\&n=fdE-9_eEW1W6yh_s\&q=85\&s=244aad2a078914626bd6f4a733537af5)

## Transcribe a YouTube video

**1. Paste the link**

Click **YouTube link** and paste the video's address in **YouTube link**. "This link works." shows when Hamsa Media recognises it.

![The Transcribe a YouTube video dialog with a link pasted and This link works. under it](https://mintcdn.com/hamsa-452fa79a/fdE-9_eEW1W6yh_s/images/media/speech-to-text/youtube-link-dialog-light.webp?fit=max\&auto=format\&n=fdE-9_eEW1W6yh_s\&q=85\&s=34a74a2ceea54162921bbaafd0c19bcd)

**2. Load the video**

Click **Continue**. The video appears with its title from YouTube.

**3. Name and set the language**

Change the **Title** if you want, and pick the **Main language**.

![The YouTube video loaded in the dialog, with its Title filled in from YouTube and the Main language below](https://mintcdn.com/hamsa-452fa79a/fdE-9_eEW1W6yh_s/images/media/speech-to-text/youtube-preview-light.webp?fit=max\&auto=format\&n=fdE-9_eEW1W6yh_s\&q=85\&s=ea6e07c439012ab8a9ca80634a9c1057)

**4. Start**

Click **Transcribe**. Hamsa Media fetches the audio from YouTube and transcribes it.

Links to a single video work in these forms: `youtube.com/watch?v=…`, `youtu.be/…`, `youtube.com/shorts/…`, `youtube.com/live/…`, `youtube.com/embed/…` and `music.youtube.com/watch?v=…`. A link to a channel or playlist shows "This is not a YouTube video link."

Videos longer than 1 hour are refused when you click **Transcribe**: "The YouTube video is too long, the maximum allowed duration is 1 hour!"

Private or unavailable videos are refused too: "This YouTube video is private or unavailable!" So are live streams while they're on air: "YouTube live streams are not supported, please try again after the stream has ended!" Use a public or unlisted video, or upload the audio as a file.

## Record with your microphone

**1. Open the recorder**

Click **Record**. The browser asks for the microphone the first time; allow it.

![The Record audio dialog before recording, with the microphone button and 00:00](https://mintcdn.com/hamsa-452fa79a/fdE-9_eEW1W6yh_s/images/media/speech-to-text/record-dialog-light.webp?fit=max\&auto=format\&n=fdE-9_eEW1W6yh_s\&q=85\&s=3e90d8a78c50b5b06a66d573f5087ef1)

**2. Record**

Click the microphone (**Start recording**) and speak. Use **Pause** and **Resume** as you need, then **Stop**.

**3. Check it**

Play the recording back. **Retake** records again; **Delete recording** removes it.

**4. Name and start**

Give it a **Title**, pick the **Main language** and click **Transcribe**.

A recording must be at least 30 seconds long ("Recording must be at least 30 seconds"). If the browser can't use the microphone you see "The microphone is not available. Check the browser permissions." or "No microphone was found on this device."

In projects with [live speech to text](https://docs.tryhamsa.com/media/speech-to-text/live.md), this card is **Record live** and opens a live session instead, where the text appears as you speak.

## What happens next

The transcript appears at the top of the list as **Pending** while it is transcribed. Leave the page if you like: the [Activity](https://docs.tryhamsa.com/media/workspace/activity-and-notifications.md) tray follows the job and tells you "Transcript ready" or "Transcript failed", and you get an email when it's ready unless you've turned job emails off.

| Status | What it means | What you can do |
| - | - | - |
| **Pending** | Uploading or being transcribed | Wait. A pending transcript can't be opened, selected or deleted |
| **Completed** | The transcript is ready | Click the row to open it in the [editor](https://docs.tryhamsa.com/media/speech-to-text/transcript-editor.md) |
| **Failed** | Transcription didn't finish | **Try again**, or delete it |

The list has the columns **Title**, **Status**, **Cost**, **Source** (Upload, YouTube or Recording) and **Created**. Search by title with "Search transcripts" and filter by status. Sorting, columns and filters work as in every list; see [Lists and uploads](https://docs.tryhamsa.com/media/workspace/lists-and-uploads.md).

## Try a failed job again

**1. Pick the failed transcript**

Open the row's menu (or find it in the **Activity** tray) and choose **Try again**.

![The menu of a failed transcript in the list, with View, Try again and Delete](https://mintcdn.com/hamsa-452fa79a/fdE-9_eEW1W6yh_s/images/media/speech-to-text/failed-row-menu-light.webp?fit=max\&auto=format\&n=fdE-9_eEW1W6yh_s\&q=85\&s=6fbd6ebbe6a7e4083e2c264a4012ce0c)

**2. Confirm**

**Run this job again?** explains that it runs with the same settings and uses credits like the first run. If the job didn't keep its language, choose the **Main language** here.

![The Run this job again? dialog for a failed transcript, asking for the Main language, with Run again](https://mintcdn.com/hamsa-452fa79a/fdE-9_eEW1W6yh_s/images/media/speech-to-text/try-again-dialog-light.webp?fit=max\&auto=format\&n=fdE-9_eEW1W6yh_s\&q=85\&s=7d31375db189e5a86da9e7a4fe1164c2)

**3. Run it**

Click **Run again**. "Started again" confirms it, and a new transcript starts from the same audio and title.

## Delete transcripts

Choose **Delete** in a row's menu. **Delete transcript?** warns that the transcript and its audio are deleted for good; confirm with **Delete**. The row leaves the list at once and you can undo for a few seconds. To delete or download several at once, select their rows. See [Lists and uploads](https://docs.tryhamsa.com/media/workspace/lists-and-uploads.md).

![The Delete transcript? dialog naming the transcript, with Cancel and Delete](https://mintcdn.com/hamsa-452fa79a/fdE-9_eEW1W6yh_s/images/media/speech-to-text/delete-transcript-dialog-light.webp?fit=max\&auto=format\&n=fdE-9_eEW1W6yh_s\&q=85\&s=ca1925d3910ef10eda4e545aa693ec52)

## Start a transcript from the API

You can create the same job from your own system with an API key. Upload the file somewhere Hamsa can download it (or use a YouTube link) and send its address:

```bash theme={null}
curl -X POST https://api.tryhamsa.com/v2/jobs \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TRANSCRIPTION",
    "projectId": "YOUR_PROJECT_ID",
    "mediaUrl": "https://example.com/interview.mp3",
    "title": "Customer interview",
    "language": "ar",
    "webhookUrl": "https://example.com/hamsa/transcripts"
  }'
```

```json theme={null}
{
  "success": true,
  "message": "Transcription started, you will receive en email when it's ready",
  "data": { "jobId": "5d3c9a1e-7b2f-4c11-9a0e-2f6b8e4d1c90" }
}
```

`language` is `ar` or `en`. `webhookUrl` (optional) is called when the transcript is ready; add `webhookAuth` with `authKey` and `authSecret`, and the call carries the header `Authorization: <authKey> <authSecret>` (for example `Bearer abc123`). The job then appears in the app's list like any other. For keys, see [API keys](https://docs.tryhamsa.com/overview/create-api-keys.md); for the full request and the webhook payload, see the API reference.

## Good to know

* One language per transcript. A recording that switches between Arabic and English is transcribed in the language you chose.
* Switching project while files upload stops the uploads; nothing is created in the old project.
* If you close the upload dialog with files chosen and nothing started, it asks before dropping them.
* Every member of the project can start transcripts, whatever their role. See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md#in-hamsa-media).

## Related

> [card] [Transcript editor](https://docs.tryhamsa.com/media/speech-to-text/transcript-editor.md)
>
> Read, correct and navigate the finished transcript.

> [card] [Speech to text overview](https://docs.tryhamsa.com/media/speech-to-text/overview.md)
>
> Languages, what a transcript contains, credits.

> [card] [Live speech to text](https://docs.tryhamsa.com/media/speech-to-text/live.md)
>
> See the text as you speak.

> [card] [Activity and notifications](https://docs.tryhamsa.com/media/workspace/activity-and-notifications.md)
>
> Follow jobs and get told when they finish.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.