> ## 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.

# How Hamsa Media fits together

> The ideas behind Hamsa Media in one place: projects and members, jobs and statuses, credits per service, voices, dictionaries, languages and permissions.

This page explains the main ideas in Hamsa Media and how they connect, one short section each. Read it once after the [quickstart](https://docs.tryhamsa.com/media/quickstart.md), then follow the links when you need the detail.

## Projects and members

A project is the shared space your team works in. Transcripts, text to speech history, voice overs, AI docs, web reader sites, custom voices, dictionaries, members and API keys all live in a project. Switch projects in the header and you see a different set.

Projects are the same in Hamsa Media and [Hamsa Agents](https://docs.tryhamsa.com/agents/introduction.md): a project made in one app appears in the other, with the same members and roles. Each member is an **Owner**, **Admin** or **User**. See [Projects](https://docs.tryhamsa.com/overview/projects/overview.md) and [Team members](https://docs.tryhamsa.com/overview/projects/team-collaboration.md).

Some work in a project is personal. Other members don't see it in their lists:

* your [text to speech history](https://docs.tryhamsa.com/media/text-to-speech/history.md#whose-takes-you-see),
* your [voice overs](https://docs.tryhamsa.com/media/voice-overs/overview.md#who-can-use-it),
* the [web reader](https://docs.tryhamsa.com/media/web-reader/overview.md#who-can-use-it) sites you added,
* your favorite voices and your [project defaults](https://docs.tryhamsa.com/media/workspace/project-defaults.md) (kept in your browser).

Transcripts, AI docs, project voices and dictionaries are the project's.

## Jobs and statuses

Most things you start in Hamsa Media run as a job in the background: a transcript, a speech take, an AI doc, a voice over and its videos. You can start one, move on, and come back. The [Activity](https://docs.tryhamsa.com/media/workspace/activity-and-notifications.md) tray in the header follows every job while it runs, and **Recent work** on [Home](https://docs.tryhamsa.com/media/workspace/home.md) shows the newest ones.

![The Activity tray: a transcript In progress under Running, and recent jobs marked Completed or Failed with a Try again button](https://mintcdn.com/hamsa-452fa79a/SjdNHyLOJ-5kYaqE/images/media/workspace/activity-tray-light.webp?fit=max\&auto=format\&n=SjdNHyLOJ-5kYaqE\&q=85\&s=2336ec3495125bc4ab0a153e8f880be0)

| Status | What it means |
| - | - |
| **Pending** | Waiting, uploading or being processed. A pending transcript or AI doc can't be opened yet. |
| **In progress** | Being processed (shown in Activity and Recent work). |
| **Completed** | Ready to open, play, edit or download. |
| **Failed** | It didn't finish. You aren't charged for a failed job. |

Voice overs use their own words: **Generating**, **Ready** (prompt options waiting for you to pick one), **Generating video** and **Failed**. Text to speech keeps only finished takes; a generation that fails leaves nothing in History.

A failed transcript, speech take or voice over video can run again with **Try again** in the Activity tray, and a transcript from its row menu too. A failed AI doc or voice over is made again from its own page. See [Run a failed job again](https://docs.tryhamsa.com/media/workspace/activity-and-notifications.md#run-a-failed-job-again).

## Credits

Every service is paid for in credits. Credits, the plan and the balance belong to the project Owner's account, not to a project: every project that Owner has, in Hamsa Media and Hamsa Agents, spends from the same balance.

| Service | What costs credits | Price the app shows |
| - | - | - |
| [Speech to text](https://docs.tryhamsa.com/media/speech-to-text/overview.md#credits) | The length of the audio, counted to the second, when the transcript is ready | 1 credit a minute |
| [Text to speech](https://docs.tryhamsa.com/media/text-to-speech/overview.md#credits) | The length of the audio made, not the characters in the script | 2 credits a minute |
| [Voice overs](https://docs.tryhamsa.com/media/voice-overs/overview.md#credits) | Each creation, whatever its length (the three prompt options count as one), and each finished video | 10 credits a voice over, 40 a video |
| [AI docs](https://docs.tryhamsa.com/media/ai-docs/overview.md#credits) | The length of the audio, once the document is written | 2 credits a minute |
| [Web reader](https://docs.tryhamsa.com/media/web-reader/overview.md#credits) | Each reading of each article, once, when it is first made: speech by length, plus translation when the reading needs it | The text to speech rate, plus translation |

Playing, comparing, exporting and downloading cost nothing. Failed jobs aren't charged.

* **They last twelve months.** Every batch of credits, from your plan, a top-up or your sign-up gift, can be used for twelve months from the day it arrives. The batch that expires soonest is spent first.
* **You need a balance above zero to start.** With none, a new job is refused and the **Insufficient credits** dialog offers to upgrade or buy credits. A job that has started finishes, so a long one can take the balance below zero.
* **Your plan can cap use.** Some plans limit how many transcriptions you start a month and how many speech takes you make a day, and the [web reader](https://docs.tryhamsa.com/media/web-reader/overview.md) needs **Pro** or higher.

![The Your credits dialog: each batch of credits with what is left and its expiry date, and how credits work](https://mintcdn.com/hamsa-452fa79a/-M2jaaqAG__ylQZS/images/media/workspace/home-your-credits-light.webp?fit=max\&auto=format\&n=-M2jaaqAG__ylQZS\&q=85\&s=52f23900d37bd86d146f38a48e304d5b)

See [Billing](https://docs.tryhamsa.com/overview/billing.md) for plans, top-ups and the credits meter.

## Voices

A voice reads your text in text to speech, voice overs and the web reader. Each voice speaks one language, and each Arabic voice speaks one dialect.

| Kind | Where you find it | Who sees it |
| - | - | - |
| Hamsa's voices | The [Voices library](https://docs.tryhamsa.com/media/voices/voices-library.md): **Explore** and **All voices**, with filters for use case, language, dialect, style and gender | Everyone |
| Project voices | **Project voices**: voices [added from a recording](https://docs.tryhamsa.com/media/voices/add-a-voice.md) in this project, marked **Custom voice**. They show in Hamsa Agents too. | Everyone in the project |
| Favorites | **Favorites**: voices you starred | Only you, in this project |

A project voice is cloned from 3 to 20 seconds of clear speech. Owners and Admins add and delete them by default.

![The Project voices tab of the Voices library, with voices added in this project marked Custom voice](https://mintcdn.com/hamsa-452fa79a/SjdNHyLOJ-5kYaqE/images/media/voices/library-project-voices-light.webp?fit=max\&auto=format\&n=SjdNHyLOJ-5kYaqE\&q=85\&s=64201defe945a76e598a597193610fc2)

## Dictionaries

A pronunciation dictionary is a list of words (the source) and how each should be said (the correction). Before a script is read, Hamsa swaps each source for its correction; your text stays as you wrote it.

* Dictionaries belong to the project, and the same dictionaries work in [Hamsa Agents](https://docs.tryhamsa.com/agents/voices/dictionaries.md).
* You turn them on per script in text to speech (up to 10), set them in [project defaults](https://docs.tryhamsa.com/media/workspace/project-defaults.md), give them to a web reader site, or turn them on for an agent.
* **Add pronunciation** on a word in a transcript or a script saves an entry without leaving the page.
* Voice overs don't use dictionaries.

![A pronunciation dictionary open, each source word beside the correction that is read instead](https://mintcdn.com/hamsa-452fa79a/etUfiFCo8p_6XpY_/images/media/voices/dictionary-editor-light.webp?fit=max\&auto=format\&n=etUfiFCo8p_6XpY_\&q=85\&s=d7279c0b3ea30f48087220debce7bc5b)

See [Dictionaries](https://docs.tryhamsa.com/media/voices/dictionaries.md).

## Languages and dialects

| Where | What you choose |
| - | - |
| Speech to text | The **Main language** spoken: Arabic (the default) or English. There is no dialect setting. |
| Text to speech | The voice. Its language and dialect are the speech's language and dialect. |
| Voice overs | In **Prompt**, an Arabic dialect such as **MSA**, **Saudi Arabia** or **Egypt**. In **My script**, the voice's own dialect. |
| AI docs | The **Audio language** (Arabic or English) and the **Document language** (Arabic, English, or both in either order). |
| Web reader | The readings a site offers: English, Modern Standard Arabic and Arabic dialects, each with its own voice. |

Arabic dialects include Saudi Arabia, Arabic (Gulf), UAE, Kuwait, Qatar, Bahrain, Oman, Iraq, Jordan, Palestine, Syria, Lebanon, Egypt and MSA (Modern Standard Arabic). Arabic text reads right to left in transcripts, documents and exports. The app itself is in English or العربية; switch in the account menu.

## Permissions

Roles and permissions belong to the project, so they are the same in both apps.

| Who, by default | Can |
| - | - |
| Every member | Use speech to text, text to speech, voice overs, AI docs and the other services; browse, compare and star voices; view dictionaries |
| Owner and Admin | Also add and delete project voices; create, change and delete dictionaries; invite members |
| Owner | Also see billing, pay, change the plan and buy credits. The Owner can give **View** on **Billing** to other members. |

The services themselves have no permission switches: every member can always use them. The Owner can turn single permissions on or off for one member, for example **Create** on **Voices** to let a User add voices and dictionaries. Hamsa Media shows every button to every member: when you lack a permission, the action is refused with a message rather than hidden. See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md#in-hamsa-media).

API keys have their own scopes, separate from member permissions. See [API keys](https://docs.tryhamsa.com/overview/create-api-keys.md#scopes-for-hamsa-media).

## Related

> [card] [Quickstart](https://docs.tryhamsa.com/media/quickstart.md)
>
> Transcribe a file, then turn it into speech.

> [card] [Limits](https://docs.tryhamsa.com/media/reference/limits.md)
>
> Every number you can run into.

> [card] [Troubleshooting](https://docs.tryhamsa.com/media/reference/troubleshooting.md)
>
> Common problems and how to fix them.

> [card] [Billing](https://docs.tryhamsa.com/overview/billing.md)
>
> Plans, credits and how they expire.


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