Music topic

Music

import 'package:sheen/music.dart';

The parts of a music player: the cover and its glow behind the glass, a mini player above the tab bar, a seek bar, transport controls, song rows with a save button, shelves of covers, synced lyrics, a queue to reorder and equaliser bands. Titles and words are always yours; SheenMusicScope translates the few labels the widgets announce.

The player

SheenArtworkGlow blurs the cover into the page behind its child, so the glass above takes the song's colours; with Reduce Transparency it is a flat tint. SheenSeekBar previews while the finger moves and reports once on release (onSeekEnd), which is when to tell the player. SheenTransportControls puts play/pause on a large glass circle; shuffle and repeat turn the accent colour when on.

SheenArtworkGlow(
  image: NetworkImage(track.cover),
  child: Column(children: [
    SheenArtwork(image: NetworkImage(track.cover), size: 300, radius: 20),
    SheenSeekBar(position: state.position, duration: state.duration, onSeekEnd: player.seek),
    SheenTransportControls(
      playing: state.playing,
      onPlayPause: player.toggle,
      onNext: player.next,
      onPrevious: player.previous,
      shuffle: state.shuffle,
      onShuffle: player.toggleShuffle,
      repeat: state.repeat,
      onRepeat: player.cycleRepeat,
    ),
  ]),
);

Media controls keep their direction in right-to-left text, as Apple's guidelines ask; times stay left to right.

Mini player

SheenMiniPlayer sits above SheenTabBar. A tap or an upward drag opens the player; a sideways swipe changes the song. Give the cover a heroTag to fly it into the player.

Songs and shelves

SheenTrackRow shows a song with its save state (SheenTrackSave.available, saving with a ring, saved) and a menu button; a long press opens the menu too. The current song shows its title in the accent and SheenPlayingBars. SheenShelf holds SheenArtworkTiles that scroll sideways; artists are round.

SheenTrackRow(
  title: track.title,
  subtitle: track.artist,
  meta: track.plays,
  artwork: NetworkImage(track.thumb),
  current: track.id == state.currentId,
  playing: state.playing,
  save: store.saveStateOf(track.id),
  saveProgress: store.progressOf(track.id),
  onTap: () => player.play(tracks, index),
  onSave: () => store.toggle(track),
  onMore: () => openMenu(track),
);

Lyrics, queue and equaliser

SheenLyricsView scrolls synced lines by itself and stops following for a few seconds after the user scrolls; a tap on a line seeks there. SheenReorderList gives each row a drag handle and removes a row on a swipe; onReorder gets the old and the new index. SheenBandSlider is one equaliser band in dB with its centre at 0.

Long audio: books and podcasts

The same player serves an audiobook with a few swaps. onSkipBack and onSkipForward replace previous and next with "back 15" and "forward 30" buttons; leading and trailing take the places of shuffle and repeat:

SheenTransportControls(
  playing: state.playing,
  onPlayPause: player.toggle,
  onSkipBack: () => player.seekBy(const Duration(seconds: -15)),
  onSkipForward: () => player.seekBy(const Duration(seconds: 30)),
  leading: SheenPressable(onTap: openSpeed, child: Text(formatSheenSpeed(state.speed))),
  trailing: sleepButton,
)

SheenSeekBar(marks: [for (final c in chapters) c.start], rate: state.speed) ticks where chapters start and shows the real time left at the chosen speed. Put SheenSpeedPicker and SheenChapterList in a sheet; SheenChapterList shows each chapter's length on the right and where it starts under the title; pass length (of the audio) so the last chapter has one too. currentSheenChapter tells which chapter holds a position. SheenResumeCard is the "Continue listening" card for a home page, SheenTagRow lists small facts under a row, and SheenArtwork(book: true) draws a 3:4 cover.

Words

SheenMusicScope(
  strings: const SheenMusicStrings(play: 'Lecture', pause: 'Pause', next: 'Suivant'),
  child: app,
)

Classes

SheenArtwork

A song's or album's cover: a square image clipped to radius, or a music glyph on a quiet ground when there is no image or it fails to load. A hairline edge keeps a dark cover apart from a dark page.

SheenArtworkGlow

The ground of a player or an album page: the cover, blurred and saturated into a soft glow, fading into the page's background, so the glass above takes the song's colours.

SheenArtworkTile

A cover with one or two lines under it, for a shelf of albums, mixes or artists. Artists are round and centred.

SheenBandSlider

One band of an equaliser: a vertical slider in decibels with its centre at 0 dB, the value above and the band's name below. The fill grows from the centre up (boost) or down (cut). A screen reader moves it 1 dB at a time.

SheenChapter

One chapter of a long recording: its title and where it starts.

SheenChapterList

The chapters of a long recording as rows: the title, where it starts and how long it is, the chapter playing in the accent colour, the ones already heard dimmed. A tap picks a chapter.

SheenLyricsLine

One timed line of lyrics.

SheenLyricsView

Synced lyrics: large lines, the one being sung bright and the rest dim, scrolling by themselves to keep the current line in the upper third. A tap on a line jumps the song there. With no timed lines, plain lyrics show as text.

SheenMiniPlayer

The glass bar above the tab bar that shows what plays: the cover, title and artist, play/pause and next, and a thin progress line along its foot.

SheenMusicScope

Provides SheenMusicStrings to the music widgets below it.

SheenMusicStrings

The words the music widgets show or announce when you give them none.

SheenPlayingBars

Three small bars that rise and fall while a song plays, in the accent colour, as the playing row of a list shows.

SheenReorderList<T>

A list whose rows can be dragged by a handle into a new order and swiped away, as a queue or a playlist is edited.

SheenResumeCard

The "Continue listening" card of long audio: the cover, the title, what is left, a progress line and a play button. Show it while a book or episode is unfinished.

SheenSeekBar

The seek line of a player: a thin track that thickens under the finger, the played part in the text colour, the buffered part fainter, and the time played and the time left under it in tabular figures.

SheenShelf

A titled row of tiles that scrolls sideways, with an optional "See all" link, as on a music home page.

SheenSkipButton

A "back 15" or "forward 30" button for long audio: a circular arrow with the number of seconds inside.

SheenSpeedPicker

The playback speed choice of long audio: one row of equal buttons, the chosen one filled.

SheenTag

One small label of a SheenTagRow; its tone picks the text colour (neutral by default).

SheenTagRow

Small facts under a row, as rounded labels that wrap: "Whole book · Ukrainian · 2 parts joined".

SheenTrackRow

One song in a list: its cover, title, artist and a short fact ("4.1M plays", "3:56"), with a save button and a menu button at the end.

SheenTransportControls

The row of a player's controls: shuffle, previous, play/pause on a large glass circle, next and repeat.

Functions

currentSheenChapter(List<SheenChapter> chapters, Duration position) → int

The index of the chapter that holds position in chapters (sorted by start), or -1 when there are none or position is before the first.

formatSheenDuration(Duration d) → String

A time as a player shows it: 1:30, 0:05, 1:02:03, or -2:27 for time left.

formatSheenLength(Duration d, SheenMusicStrings s) → String

A length as a listener says it: "30 min", "1 h 5 min" (never "0 min").

formatSheenSpeed(double speed) → String

A playback speed as a player shows it: 1×, 1.25×, 0.8×.

Enums

SheenRepeatMode

What repeats.

SheenTrackSave

Whether a song can be stored on the device, is being stored, or is stored.