Files
synchronicity/docs/audio-player-ui-design-principles.md
Greg ShuflinandClaude Opus 5.5 3a102d8d61 gui: the player's transport is centered, between flanks that can't move it
The desktop anchored back/play/next at the left of the action row so an
optional control appearing on the right couldn't move the play button. With
Music's secondary cluster empty, that just looked shoved aside. The action
row is now three slots: two flex_1 flanks that split the leftover width
equally, with the transport between them. The play button sits dead center
under the scrubber and still doesn't move when a secondary control comes or
goes.

ADR 0046 and the design-principles doc are updated to match, and the ADR's
open question (a left flank beside the artwork) is closed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 02:17:28 -08:00

9.9 KiB
Raw Permalink Blame History

Audio Player UI Design Principles

Implemented, and recorded as ADR 0046. The two players are rust/gui-app/src/components/player_controls.rs (gpui desktop) and android/app/src/main/java/com/gregshuflin/synchronicity/ui/PlayerControls.kt (Compose); each agent's configuration lives with the agent — music_player()/podcast_player() and MUSIC_PLAYER/PODCAST_PLAYER. The desktop's visualization slot exists and is empty; Android's player has no visualization or artwork region, since nothing used them. See the ADR for what filling the slot costs.

Goal

One visual language for music and podcasts, with desktop and mobile implemented as separate widgets. Features should be configurable without changing the player's basic identity or layout.

What syncs, and what doesn't

Live player state is local to the node it is playing on, and is never sent to another one. Playing or paused, the second the scrubber is at right now, the volume, which machine's speakers this is coming out of: none of it leaves the node. What syncs is the progress artifact — where the listener got to, written as they listen (ArtifactKind::ListenProgress, ReadingPosition for its reading equivalent) and read when the same document is opened somewhere else.

The difference is the whole point of the feature and easy to lose. "Pause a podcast on the phone, resume on the desktop" (docs/sync-management.md) is a claim about resuming, not about the desktop starting to play because the phone did — a device that began making noise because another device did would be acting on its own, which is not what any of this is for. The same applies in the smaller: a position arriving from another node while an episode is playing here must not seek under the listener, because CLAUDE.md's rule about never disrupting what the user is doing covers playback as much as it covers a list they are scrolling.

So a player screen may follow the store for what it shows — an episode's remembered position while it is not playing, the podcast's speed — but never for what it does. This holds for music and podcasts today, and for video when it exists.

What a speed pick writes

Podcasts only; Music has no rate control. Picking a speed — a preset, a custom speed from the menu, or one confirmed on the slider — makes it that podcast's speed, on its feed's document, so every episode of it starts there on every node. It is not per episode, and there is no one speed for all of Podcasts, and no node-local fallback either: a podcast with no speed plays at 1×. A speed confirmed on the slider that the menu doesn't already offer also joins the custom speeds, a synced Podcasts-wide list on the agent's settings document, from which the slider dialog can remove it. Dragging the slider writes nothing. agents::podcast::speed holds the rule and both writes.

The speed is read when an episode starts, on the same principle as the position: a speed picked on another node never retunes playback already under way here.

When the progress artifact is written

Both players write it on the same schedule, and the schedule is here rather than in either of them because two players disagreeing about it is invisible until someone compares two devices — and every write syncs, so the cadence is a claim about the ensemble's traffic, not a local detail.

  • Every 5 seconds while playing, and no more often. This bounds only what a hard kill of the app loses, since every stopping point flushes anyway.
  • Flushed immediately whenever playback stops being the thing happening: pause, stop, loading a different track. Pausing and walking away is the ordinary way a listener stops, and it must not lose up to five seconds.
  • Leaving the screen is not one of those moments, because it does not stop playback: Android's transport is a MediaSessionService that keeps going from the notification, and the desktop's bar sits under every tab of the agent. So the write loop lives with the transport, not with the screen showing it — Android's ListenProgressRecorder, and on the desktop the subscription PodcastsView holds rather than the detail screen under it. A loop that ends with a composition records an hour of lock-screen listening as the two minutes before the user navigated away.
  • Nothing below 3 seconds in. A preview tap should not mark an episode started, and "started" is a visible state — it puts a position on a row that read as untouched a moment ago.
  • The end of the track writes Finished, not a position. An episode played to the end should read as finished on every node, not as a position two seconds short of the end that a rounding difference could reopen.

The desktop's constants are PROGRESS_EMIT_INTERVAL/MIN_PROGRESS_SECS in player_controls.rs; Android's are PROGRESS_WRITE_INTERVAL_MS/ MIN_PROGRESS_MS in PodcastRepository.kt, which is where the writer is and so where the floor is enforced for every path that writes one. They are two spellings of this section, not two decisions.

Shared structure

Treat the player as four conceptual regions:

  1. Metadata — what is playing
  2. Visualization — optional representation of the audio/content
  3. Timeline — where playback is
  4. Actions — what the user can do

Keep these roles visually distinct.

Metadata

  • Center primary and secondary metadata over the scrubber.
  • Primary text: track or episode title.
  • Secondary text: artist or podcast/show name.
  • Center relative to the whole player/scrubber, not relative to the transport controls.
  • Allow truncation or wrapping without moving the playback controls.

Visualization slot

Place an optional visualization above the scrubber.

Examples:

  • Music: spectrum analyzer, waveform, oscilloscope, or other decorative audio visualization.
  • Podcast: waveform, chapter/segment information, or nothing.

Principles:

  • Treat visualization as subordinate to playback functionality.
  • Keep the normal visualization compact; it should not compete with controls.
  • Do not place moving visualization between primary and secondary action groups.
  • The slot should be optional without changing the rest of the layout.

Timeline / scrubber

  • Give the scrubber its own clear horizontal region.
  • Show elapsed and total/remaining time where useful.
  • For long-form audio, remaining time is especially valuable.
  • Make the interactive hit area substantially larger than the visible line.
  • Keep timeline placement consistent between music and podcast configurations.

Desktop layout

Preferred vertical order:

        Primary metadata
       Secondary metadata

       Optional visualization

elapsed ━━━━━━━━━●━━━━━━━━ remaining

[ leading ]     [ primary transport ]     [ secondary actions ]

Primary transport

Center the large, frequently used controls under the scrubber. Center them on their own: the flanking slots on either side split the remaining width equally, so whatever sits in them never moves the transport.

Music:

previous    play/pause    next

Podcast:

back 15s    play/pause    forward 30s

The intervals are a configured value, not part of the design — and no glyph carries the number, so changing them (eventually: a user setting) changes only where the value comes from. The shipped default is 15s each way. See ADR 0046.

  • Play/pause should be the strongest visual control.
  • Keep the primary cluster spatially stable across configurations.

Secondary actions

Put optional / lower-frequency controls in the flanks, beside the primary transport and never inside it. The right flank is the default; the left is for a control that reads better there.

Possible controls:

  • playback speed
  • shuffle / repeat
  • chapters
  • queue
  • sleep timer
  • volume / output
  • overflow menu

As width decreases, collapse or hide controls from the flanks first.

Do not center the entire action row as one group: then an optional control would shift the primary transport by half its own width. Center the transport, and let the flanks fill in around it.

Mobile layout

Use the same conceptual sequence, adapted to a narrow/tall layout:

        Artwork

     Primary metadata
    Secondary metadata

   Optional visualization

elapsed ━━━━━●━━━━━ remaining

     primary transport

     secondary actions
  • Prefer scrubber above transport controls.
  • Keep transport controls large and thumb-friendly.
  • Preserve the same iconography, typography, scrubber treatment, and visualization style as desktop.
  • Mobile and desktop need not use identical geometry; they should clearly look like variants of the same player.

Configuration model

Avoid hard-coded “music mode” and “podcast mode” where possible. Model capabilities instead.

Player
├── artwork?
├── metadata
│   ├── primary
│   └── secondary
├── visualization?
├── timeline
├── primary_actions
└── secondary_actions

Typical configurations:

Capability Music Podcast
Primary back Previous track Rewind N seconds
Primary forward Next track Forward N seconds
Play/pause Yes Yes
Speed Usually off Usually on
Chapters Rare Optional
Shuffle/repeat Optional Usually off
Queue Optional Optional
Visualization Spectrum/waveform/etc. Waveform/segments/none

Visual invariants

Across desktop/mobile and music/podcast configurations:

  • Metadata remains centered.
  • Visualization stays directly above the timeline.
  • Timeline styling remains consistent.
  • Play/pause is visually dominant.
  • Primary transport remains clearly separated from secondary controls.
  • Optional functionality should appear/disappear without shifting the player's major landmarks.
  • Decorative motion must never compete with the controls needed for playback.