Tamed can translate song lyrics into your language of choice using a large language model of your choosing. The translation engine works with both synced (LRC-format) and plain lyrics: it extracts each lyric line, batches them for efficiency, sends them to your configured AI provider, and reassembles the translated result into the original format. All processing happens through direct API calls from your device — no Tamed server is involved.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/calmerism/Tamed/llms.txt
Use this file to discover all available pages before exploring further.
Lyrics content is sent to your configured AI provider’s API for translation. If privacy is a concern, consider using the CUSTOM provider option with a locally-hosted model such as Ollama, which keeps everything on-device.
Supported Providers
Tamed supports six provider options defined in theAiProvider enum:
ChatGPT
Calls the OpenAI Chat Completions API at
https://api.openai.com/v1/chat/completions. Default model: gpt-4o. Standard OpenAI API key required.Gemini
Calls the Google AI
generateContent endpoint. Default model: gemini-3.5-flash. Requires a Google AI Studio API key.Claude
Calls the Anthropic Messages API at
https://api.anthropic.com/v1/messages. Default model: claude-3-haiku-20240307. Requires an Anthropic API key.OpenRouter
Routes through openrouter.ai, giving you access to dozens of models from a single API key. Default model:
openrouter/auto.Custom
Any OpenAI-compatible endpoint you supply. Useful for self-hosted models (e.g. Ollama, LM Studio, vLLM). Requires both an API key and a custom endpoint URL.
None
Disables AI translation entirely. The AI service will throw an exception if called while set to
NONE.Setup
Select a provider
Choose your preferred provider from the dropdown. This sets
AiProviderKey (string). Available values: CHATGPT, GEMINI, CLAUDE, OPENROUTER, CUSTOM, NONE.Enter your API key
Paste your API key into the API key field (
AiApiKeyKey). The key is stored securely in the app’s DataStore and sent only to the configured provider’s endpoint.Set a custom endpoint (CUSTOM or OPENROUTER)
If you selected CUSTOM, enter the full base URL of your OpenAI-compatible API in the custom endpoint field (
AiCustomEndpointKey). For example, a locally-hosted Ollama instance might use http://localhost:11434/v1/chat/completions. This field is ignored for all other providers.Select a model
Tamed can fetch the available models for your provider (ChatGPT, Gemini, Claude, and OpenRouter all support model listing). Select from the list (
AiSelectedModelKey) or type a model identifier manually into the custom model field (AiCustomModelKey).If no model is set, Tamed uses a sensible default per provider:| Provider | Default model |
|---|---|
| CHATGPT | gpt-4o |
| GEMINI | gemini-3.5-flash |
| CLAUDE | claude-3-haiku-20240307 |
| OPENROUTER | openrouter/auto |
Validate your configuration
Tamed runs a lightweight test call to verify your credentials. The result is stored in
AiApiValidationStatusKey and shown in the settings UI:| Status | Meaning |
|---|---|
UNKNOWN | No validation has been attempted yet |
SUCCESS | The test call returned "OK" as expected |
FAILED | The API key is invalid, the model is unavailable, or the endpoint is unreachable |
Translation Settings
| Key | Type | Description |
|---|---|---|
EnableTranslatorKey | boolean | Master toggle — enables or disables all AI translation |
TranslateLyricsKey | boolean | Enables on-screen lyrics translation in the player view |
TranslatorTargetLangKey | string | Language name for the translation target (e.g. "ENGLISH", "JAPANESE", "FRENCH") |
TranslatorContextsKey | string | Comma-separated context tokens sent to the model (e.g. "{song},{artist}") |
Supported target languages
TranslatorTargetLangKey stores a language name in UPPER_CASE, matching the enum entries used by the translation library (for example ENGLISH, JAPANESE, KOREAN, CHINESE, FRENCH, GERMAN, SPANISH, PORTUGUESE, RUSSIAN, ARABIC, HINDI). The default value when the key is unset is ENGLISH. Values are normalized before being passed to the AI provider — underscores are replaced with spaces and the result is title-cased (e.g. BRAZILIAN_PORTUGUESE becomes Brazilian Portuguese).
How Translation Works
TheAiLyricsTranslator extracts individual lyric lines from both LRC-synced and plain-text formats, then batches them into chunks of up to 80 lines or 6,000 characters before sending each batch to the AI provider. The translated lines are then reinserted into the original structure, preserving all timestamps and formatting.
The model is instructed to:
- Preserve meaning, tone, names, and repeated hooks
- Match the profanity level of the original
- Return exactly the same number of lines as it received
- Omit any markdown, explanations, or extra output
Cost Considerations
Romanization (No AI Required)
For Japanese, Korean, Chinese, and Hindi lyrics, Tamed includes offline romanization that works without any AI provider or internet connection:| Key | Language |
|---|---|
LyricsRomanizeJapaneseKey | Japanese → rōmaji |
LyricsRomanizeKoreanKey | Korean → Revised Romanization |
LyricsRomanizeChineseKey | Chinese → Pinyin |
LyricsRomanizeHindiKey | Hindi → Latin transliteration |
LyricsRomanizeOtherLanguagesKey | Other languages (broad coverage) |