Audio Player System Architecture Summary

Core design goal

Provide a seamless, flexible, and intuitive audio experience across different content types (Narration, Preview, Music), ensuring that players do not conflict and that user control feels natural on both desktop and mobile.

Player types and roles

Narration Player (`data-role="narration"`)

Primary voice content (e.g., story narration).
Can control playback speed via toggle.
Pauses other players (Preview or Music) when active.
Automatically reduces music volume on the desktop when playing.

Preview Player (`data-role="preview"`)

Only for Cinema Members
Short introductory or teaser audio.
Pauses other players when active.

Music Player (`data-role="music"`)

Background ambient music, optionally looped.
Volume automatically reduced to 10% (0.1) when narration or preview plays on the desktop.
Volume restores to the original level when other players are paused.
On mobile, no volume reduction (instead, the music player is paused completely to avoid conflicts).

Cross-player interaction logic

Desktop

Multiple players can play. The music volume automatically lowers when either narration or preview is active.
Narration and preview players cannot play simultaneously:
- Starting narration pauses Preview if it’s playing.
- Starting preview pauses narration if it’s playing.
When Narration or Preview is paused, music volume smoothly restores to its original level.

Mobile

Only one player is active at a time.
Any new player automatically pauses any other playing audio (since mobile OS restricts volume control).
Avoids needing to scroll to find “stop” buttons.

Playback speed customization

Default speed is set using an article tag (e.g., meta-player-speed-1.1).
Alternative speeds are 1.0 (normal), 1.2 (faster), 1.3 (fastest), and 0.8 (slowest).
Faster speeds are ideal for rapid story listening or as a time-saver when proofreading long stories.
Default speed is set at the code level by changing speedIndex based on tag value, avoiding complicated metafields.
User can select speed by clicking the Duration on Narration or Preview players.
Clicking Duration on the music player activates looping.

Tag-based workflow benefits

Easy to apply speed settings to multiple articles in Shopify admin without editing each one.
Prevents potential metafield assignment errors.
Tag auto-suggest feature reduces the chance of typos (e.g., typing “1.1” quickly filters to correct tag).

UX clarity

Optional player note appears below the player when a custom speed tag is present, encouraging the user to adjust as needed.
On-page display:
“Click ⌲ or Duration or speed to change playback pace”

Why this architecture excels

Strong separation of roles and priorities.
Smooth, automated cross-player interaction.
Tag-based speed control scales easily.
Thoughtful fallback and error prevention.
Consistent experience across devices.
Maintains editorial control with minimal maintenance.