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>
9.9 KiB
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
MediaSessionServicethat 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'sListenProgressRecorder, and on the desktop the subscriptionPodcastsViewholds 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:
- Metadata — what is playing
- Visualization — optional representation of the audio/content
- Timeline — where playback is
- 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.