Tamed is built around a robust audio engine powered by AndroidX Media3 (ExoPlayer) with aDocumentation 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.
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
- ID3 tags for MP3 files
- Vorbis Comments for FLAC and OGG
- MP4 atoms for M4A and ALAC
Queue Types
Tamed models playback as a typedQueue 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 theCrossfadeAudio 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).
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:| Key | Type | Description |
|---|---|---|
SkipSilenceKey | Boolean | Enable the SilenceSkippingAudioProcessor |
SkipSilenceInstantKey | Boolean | Skip immediately rather than fading through silence |
Audio Normalization
WhenAudioNormalizationKey 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
WhenPersistentQueueKey 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 viaRepeatModeKey:
REPEAT_MODE_OFF— play through onceREPEAT_MODE_ONE— loop the current trackREPEAT_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
| Key | Behaviour |
|---|---|
AutoStartOnBluetoothKey | Resumes playback when a Bluetooth audio device connects |
PauseOnDeviceMuteKey | Pauses automatically when the device volume is set to zero |
Equalizer
The equalizer system is built on Android’s nativeandroid.media.audiofx APIs, wrapped in two data classes defined in EqualizerModels.kt.
EqProfile
Stores a named preset that can be saved and restored:EqSettings
Represents the live, applied equalizer state: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:PlayerStreamClient Enum
Selects which YouTube client context is used to resolve stream URLs:JioSaavn Streaming
Tamed includes native JioSaavn streaming support, selectable viaEnableSaavnStreamingKey. Quality is set per SaavnAudioQuality:
| Enum Value | API Value | Label |
|---|---|---|
QUALITY_320 | 320kbps | High (320 kbps) |
QUALITY_160 | 160kbps | Medium (160 kbps) |
QUALITY_96 | 96kbps | Low (96 kbps) |
Offline Downloads
Tamed usesExoDownloadService 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.