Track List Components

Overview

Track list components render audio tracks in various contexts including local music libraries, albums, playlists, and search results. Each component includes artwork, metadata, and contextual actions.

LocalTracksList

Scrollable list of local music tracks with alphabetical fast scrolling. Location: ui/screens/LocalMusicScreen.kt:479

Parameters

tracks

List<LocalTrack>

required

List of local tracks to display

state

LazyListState

default:"rememberLazyListState()"

Scroll state for the lazy list (supports state restoration)

onTrackClick

(LocalTrack, List<LocalTrack>) -> Unit

required

Callback when track is clicked. Receives the track and full track list for queue context.

Callback to share a track file

onDelete

(LocalTrack) -> Unit

required

Callback to delete a track from device

onEdit

(LocalTrack) -> Unit

required

Callback to edit track metadata

onAddToPlaylist

(LocalTrack) -> Unit

required

Callback to add track to a playlist

totalStorage

Long

required

Total device storage in bytes for progress calculation

contentPadding

default:"0.dp"

Bottom padding for dynamic navigation bar spacing

Features

Statistics bar: Shows track count, storage usage bar, and total size in GB
Alphabetical indexing: Fast scroll bar with A-Z letters for quick navigation
Auto-sync scrolling: Current letter indicator updates based on scroll position
Format badges: Visual indicators for FLAC, WAV, MP3, AAC formats
File size display: Compact size display per track
Context menu: Share, add to playlist, details, edit, delete options

Usage Example

@Composable
fun LocalMusicTab() {
    val tracks by viewModel.tracks.collectAsState()
    val totalStorage by viewModel.totalStorage.collectAsState()
    
    LocalTracksList(
        tracks = tracks,
        onTrackClick = { track, list -> 
            playerController.playTrack(track, list)
        },
        onShare = { track -> shareTrack(track) },
        onDelete = { track -> viewModel.deleteTrack(track) },
        onEdit = { track -> showEditDialog(track) },
        onAddToPlaylist = { track -> showPlaylistPicker(track) },
        totalStorage = totalStorage,
        contentPadding = 80.dp
    )
}

LocalTrackItem

Individual track list item with album art, metadata, format badge, and context menu. Location: ui/screens/LocalMusicScreen.kt:737

Parameters

track

LocalTrack

required

Track data to display

Callback to share the track

onDelete

() -> Unit

required

Callback to delete the track

onEdit

() -> Unit

required

Callback to edit track metadata

onAddToPlaylist

(() -> Unit)?

default:"null"

Optional callback to add track to playlist

onClick

() -> Unit

required

Callback when track row is clicked

deleteLabel

String

default:"stringResource(R.string.action_delete)"

Custom label for delete menu item

Layout Structure

Album artwork: 48x48dp rounded square
Track title: Bold, 16sp, marquee scrolling for overflow
Artist name: 12sp, gray color
Format badge: FLAC (blue), WAV (amber), MP3/AAC (gray)
File size: Compact format (e.g., “3.2MB”)
Menu button: Three-dot icon for context actions

Share: Opens system share sheet for the audio file
Add to Playlist: Shows playlist picker (if callback provided)
Details: Opens TrackDetailsDialog with file information
Edit: Opens EditTrackDialog for metadata editing
Delete: Deletes the track from device (red text)

Format Badges

Visual indicators based on MIME type:

Format	Color	Background
FLAC	Blue (`#00A2E8`)	Blue at 20% opacity
WAV	Amber (`#FFC107`)	Amber at 20% opacity
MP3	Gray	Surface dark
AAC	Gray	Surface dark

AlbumGridItem

Grid item for displaying album with artwork and metadata. Location: ui/screens/LocalMusicScreen.kt:634

Parameters

album

LocalAlbum

required

Album data to display

onClick

() -> Unit

required

Callback when album is clicked

Layout

Artwork: Square aspect ratio (1:1) with 8dp rounded corners
Title: 14sp, medium weight, marquee scrolling
Artist: 12sp, gray color, marquee scrolling
Alignment: Center-aligned in column

Usage Example

LazyVerticalGrid(columns = GridCells.Fixed(2)) {
    items(albums) { album ->
        AlbumGridItem(
            album = album,
            onClick = { navigateToAlbum(album.id) }
        )
    }
}

ArtistGridItem

Grid item for displaying artist with circular avatar and track count. Location: ui/screens/LocalMusicScreen.kt:694

Parameters

artist

LocalArtist

required

Artist data to display

onClick

() -> Unit

required

Callback when artist is clicked

Layout

Avatar: 96dp circular shape with person icon placeholder
Name: 14sp, medium weight, marquee scrolling
Track count: “X songs” in gray, 12sp
Alignment: Center-aligned in column

Usage Example

LazyVerticalGrid(columns = GridCells.Fixed(3)) {
    items(artists) { artist ->
        ArtistGridItem(
            artist = artist,
            onClick = { navigateToArtist(artist.name) }
        )
    }
}

TrackListItem (Deezer)

Track list item for online Deezer tracks with download functionality. Location: ui/screens/AlbumScreen.kt:279

Parameters

track

Track

required

Deezer track data to display

index

Int

required

Track number in the list

isDownloaded

Boolean

required

Whether track is already downloaded

isDownloading

Boolean

required

Whether track is currently downloading

onDownloadClick

() -> Unit

required

Callback to initiate download

Layout Structure

Track number: Left-aligned, 32dp width
Track title: Bold, 14sp, white
Artist name: 12sp, gray (hidden if same as album)
Duration: Formatted time (mm:ss)
Preview button: 30-second preview playback
Download button: States: download icon, progress spinner, or checkmark

Download States

State	Icon	Color	Enabled
Not downloaded	Download icon	Primary	Yes
Downloading	Circular progress	Primary	No
Downloaded	Checkmark	Green	No

Usage Example

items(tracks.size) { index ->
    val track = tracks[index]
    var isDownloaded by remember { mutableStateOf(false) }
    
    LaunchedEffect(track.id) {
        isDownloaded = downloadManager.isTrackDownloaded(
            track.title,
            track.artist?.name ?: ""
        )
    }
    
    TrackListItem(
        track = track,
        index = index + 1,
        isDownloaded = isDownloaded,
        isDownloading = downloadState.currentTrackId == track.id.toString(),
        onDownloadClick = { downloadManager.startTrackDownload(track.id) }
    )
}

PlaylistTrackItem

Track item variant for playlist screens (similar to TrackListItem but with album art). Location: ui/screens/PlaylistScreen.kt:285

Key Differences from TrackListItem

Shows album artwork (48x48dp) instead of track number
Includes artist name even if it matches album
Used in playlist detail views

Parameters

Identical to TrackListItem, except:

No index parameter
Album artwork displayed from track.album?.coverSmall

FormatBadge

Compact format indicator for audio file types. Location: ui/screens/LocalMusicScreen.kt:880

Parameter

mimeType

String

required

MIME type of the audio file (e.g., “audio/flac”, “audio/mpeg”)

Format Detection

val (text, color) = when {
    mimeType.contains("flac") -> "FLAC" to Color(0xFF00A2E8)
    mimeType.contains("wav") -> "WAV" to Color(0xFFFFC107)
    mimeType.contains("mpeg") || mimeType.contains("mp3") -> "MP3" to TextGray
    mimeType.contains("mp4") || mimeType.contains("aac") -> "AAC" to TextGray
    else -> "AUDIO" to TextGray
}

Styling

Padding: 4dp horizontal, 2dp vertical
Font: 10sp, bold
Corner radius: 4dp
High-quality formats (FLAC, WAV): Colored background and text
Standard formats (MP3, AAC): Gray text on dark background

Music Player - Full-screen and mini player
Dialogs - Track details and editing dialogs

Core Services

Data Models

UI Components

Overview

LocalTracksList

Parameters

Features

Usage Example

LocalTrackItem

Parameters

Layout Structure

Context Menu Actions

Format Badges

AlbumGridItem

Parameters

Layout

Usage Example

ArtistGridItem

Parameters

Layout

Usage Example

TrackListItem (Deezer)

Parameters

Layout Structure

Download States

Usage Example

PlaylistTrackItem

Key Differences from TrackListItem

Parameters

FormatBadge

Parameter

Format Detection

Styling

Build docs developers (and LLMs) love

Core Services

Data Models

UI Components

​Overview

​LocalTracksList

​Parameters

​Features

​Usage Example

​LocalTrackItem

​Parameters

​Layout Structure

​Context Menu Actions

​Format Badges

​AlbumGridItem

​Parameters

​Layout

​Usage Example

​ArtistGridItem

​Parameters

​Layout

​Usage Example

​TrackListItem (Deezer)

​Parameters

​Layout Structure

​Download States

​Usage Example

​PlaylistTrackItem

​Key Differences from TrackListItem

​Parameters

​FormatBadge

​Parameter

​Format Detection

​Styling

​Related Components

Build docs developers (and LLMs) love

Overview

LocalTracksList

Parameters

Features

Usage Example

LocalTrackItem

Parameters

Layout Structure

Context Menu Actions

Format Badges

AlbumGridItem

Parameters

Layout

Usage Example

ArtistGridItem

Parameters

Layout

Usage Example

TrackListItem (Deezer)

Parameters

Layout Structure

Download States

Usage Example

PlaylistTrackItem

Key Differences from TrackListItem

Parameters

FormatBadge

Parameter

Format Detection

Styling

Related Components