Skip to main content

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.

Tamed is built around a robust audio engine powered by AndroidX Media3 (ExoPlayer) with a MediaLibraryService and MediaSession, giving it deep system integration—lockscreen controls, Android Auto support, and proper audio focus management. Every playback feature from crossfade to sleep timer is implemented in MusicService, which runs as a foreground service for uninterrupted listening.

Supported Formats

Tamed handles both lossless archival formats and standard compressed formats through ExoPlayer’s extractor pipeline.

Lossless Formats

FLAC, AIFF, WAV, ALAC, APE, WavPack, DSD

Standard Formats

M4A, AAC, MP3, OGG, OPUS, WMA, MKV, AMR
Tag metadata is read natively per container:
  • ID3 tags for MP3 files
  • Vorbis Comments for FLAC and OGG
  • MP4 atoms for M4A and ALAC

Queue Types

Tamed models playback as a typed Queue interface. Each queue implementation can report a title, provide an initial list of MediaItem objects, and optionally page in more tracks.

ListQueue

A static, ordered list of tracks — used when you play an album, artist, or playlist directly.

YouTubeQueue

A YouTube Music radio queue backed by WatchEndpoint, supporting auto-pagination as the mix plays.

YouTubeAlbumRadio

Loads an album’s tracks from YouTube Music and then paginates additional radio recommendations via WatchEndpoint after the album ends.

LocalAlbumRadio

Starts from a local album and follows the YouTube Music radio for that album’s playlist ID.

LocalMixQueue

Builds a mix from a local playlist by seeding with stored related songs; falls back to YouTube Music next and related recommendations if no local related songs are available.

EmptyQueue

A sentinel queue with no tracks, used as the initial state before anything is loaded.

Playback Features

Crossfade

Crossfade is handled by the CrossfadeAudio class, which spawns an overlap ExoPlayer instance to pre-buffer and smoothly blend into the next track. The duration is configured via AudioCrossfadeDurationKey (stored as an Int in milliseconds).
val AudioCrossfadeDurationKey = intPreferencesKey("audioCrossfadeDuration")
When a crossfade is active, CrossfadeAudio calculates a linear volume ramp between the main and overlap players, then performs a synchronised position handoff at the transition boundary.

Silence Skipping

Two keys control silence detection behaviour:
KeyTypeDescription
SkipSilenceKeyBooleanEnable the SilenceSkippingAudioProcessor
SkipSilenceInstantKeyBooleanSkip immediately rather than fading through silence

Audio Normalization

When AudioNormalizationKey is enabled, Tamed reads the loudnessDb or perceptualLoudnessDb fields from the stored FormatEntity and adjusts the player volume factor accordingly. The gain is clamped to a maximum safe factor of +3 dB (maxSafeGainFactor = 1.414f).

Audio Offload

AudioOffload (a Boolean preference key) enables ExoPlayer’s audio offload mode, allowing the DSP to process audio in hardware and reducing CPU wake time for battery savings during long listening sessions.

Persistent Queue

When PersistentQueueKey is true, the current queue, player position, repeat mode, shuffle state, and volume are serialised to disk on every significant change and on service destruction. On the next launch the queue is restored exactly as left.

Repeat Modes

Tamed exposes Media3’s three native repeat modes, stored via RepeatModeKey:
  • REPEAT_MODE_OFF — play through once
  • REPEAT_MODE_ONE — loop the current track
  • REPEAT_MODE_ALL — loop the entire queue

Permanent Shuffle

PermanentShuffleKey keeps shuffle mode active across restarts, so the queue is always in a shuffled order when the preference is set.

Sleep Timer

SleepTimer is a dedicated component attached to the player as a Player.Listener. It counts down from a configured duration and pauses or stops playback when the timer expires.

Volume Control

PlayerVolumeKey persists the player’s independent software volume (0.0–1.0), separate from the system media volume. Audio focus ducking applies an additional audioFocusVolumeFactor multiplier on top.

Bluetooth Auto-Start & Pause on Mute

KeyBehaviour
AutoStartOnBluetoothKeyResumes playback when a Bluetooth audio device connects
PauseOnDeviceMuteKeyPauses automatically when the device volume is set to zero

Equalizer

The equalizer system is built on Android’s native android.media.audiofx APIs, wrapped in two data classes defined in EqualizerModels.kt.

EqProfile

Stores a named preset that can be saved and restored:
@Serializable
data class EqProfile(
    val id: String,
    val name: String,
    val bandCenterFreqHz: List<Int> = emptyList(),
    val bandLevelsMb: List<Int> = emptyList(),
    val outputGainMb: Int = 0,
    val bassBoostStrength: Int = 0,
    val virtualizerStrength: Int = 0,
)

EqSettings

Represents the live, applied equalizer state:
data class EqSettings(
    val enabled: Boolean,
    val bandLevelsMb: List<Int>,
    val outputGainEnabled: Boolean,
    val outputGainMb: Int,
    val bassBoostEnabled: Boolean,
    val bassBoostStrength: Int,
    val virtualizerEnabled: Boolean,
    val virtualizerStrength: Int,
)
Custom profiles are serialised to JSON and stored in EqualizerCustomProfilesJson. The active profile ID is tracked by EqualizerSelectedProfileIdKey.
EqCapabilities is populated at runtime by querying the device’s android.media.audiofx.Equalizer for its band count, frequency range, and available system presets.

Audio Quality & Stream Client

AudioQuality Enum

Controls the target bitrate when streaming from YouTube Music:
enum class AudioQuality {
    AUTO,
    HIGH,
    HIGHEST,
    LOW,
}

PlayerStreamClient Enum

Selects which YouTube client context is used to resolve stream URLs:
enum class PlayerStreamClient {
    ANDROID_VR,
    WEB_REMIX,
    IOS,
    TVHTML5,
    ANDROID_MUSIC,
}

JioSaavn Streaming

Tamed includes native JioSaavn streaming support, selectable via EnableSaavnStreamingKey. Quality is set per SaavnAudioQuality:
Enum ValueAPI ValueLabel
QUALITY_320320kbpsHigh (320 kbps)
QUALITY_160160kbpsMedium (160 kbps)
QUALITY_9696kbpsLow (96 kbps)

Offline Downloads

Tamed uses ExoDownloadService and the Media3 DownloadManager to cache tracks for offline playback. AutoDownloadOnLikeKey triggers a download automatically whenever a song is liked. An external download manager application can also be configured via ExternalDownloaderEnabledKey and ExternalDownloaderPackageKey.

Build docs developers (and LLMs) love