🎧 Audio Player — setup
────────────────────────────────
1. Put the element on the page
────────────────────────────────

Drag Audio Player onto a mobile page. It takes the full width it is given and works out its own height.

────────────────────────────────
2. Give it audio
────────────────────────────────

For a single track, set audio_url to a direct link to the file. MP3, M4A, AAC, WAV and HLS (.m3u8) all work. Fill in track_title, artist_name and artwork_url as well — those three are what appear on the lock screen, not only inside the player.

For a playlist, point these four at lists from your database, in the same order:

• track_urls — the audio links
  
• track_titles
  
• track_artists
  
• track_artworks
  

Tick Is a list on all four. Without that box Bubble hands over a single value and your playlist ends up one track long, with no error to tell you.

Point them at the text, not at the records: Search for Audios:each item's Track, where Track is the field holding the link.

While prototyping, tracks_text is faster — one track per line:

[color=#0205d3][url=https://cdn.example.com/1.mp3]https://cdn.example.com/1.mp3[/url][/color] | Midnight City | M83 [color=#0205d3][url=https://cdn.example.com/2.mp3]https://cdn.example.com/2.mp3[/url][/color] | Outro | M83

────────────────────────────────
3. Pick a shape
────────────────────────────────

layout is Card for a now-playing screen with cover art, or Bar for a compact row that fits inside a repeating group or pinned to the bottom of the page.

artwork_style sets how much room the cover gets: Large, Compact or Hidden.

────────────────────────────────
4. Set the colours
────────────────────────────────

accent_color paints the play button, the played part of the waveform, the playhead, the queue highlight and every active control at once. theme is Dark, Light, or Auto to follow the phone.

corner_radius and inner_padding are yours. There is no border — if you want one, put the element in a group and give the group the border.

────────────────────────────────
5. Tick the checkbox defaults
────────────────────────────────

Several fields are meant to be on: show_skip_buttons, show_track_buttons, show_speed, show_shuffle_repeat, show_queue, show_times, play_in_background, lock_screen_controls, wave_pulse and show_chapter_labels.

A Bubble checkbox starts unticked, so tick the ones you want. If a control is missing from the player, this is almost always why — the element is hiding it because you told it to.

────────────────────────────────
6. Chapters (optional)
────────────────────────────────

Fill chapters_text with one line per chapter:

0:00 Introduction 1:45 The main part 4:10 Wrapping up

Or point chapter_times and chapter_titles at two lists in the same order. The waveform splits itself and the chapter name appears over the player when each one starts.

────────────────────────────────
7. Wire it to your workflows
────────────────────────────────

Fifteen actions drive the player from anywhere: Play, Pause, Toggle Play, Next Track, Previous Track, Play Track, Seek To, Skip, Set Volume, Set Muted, Set Speed, Set Shuffle, Set Repeat, Load Playlist, Go To Chapter.

Twenty-one states report back, including Current time, Duration, Progress percent, Current track index and title, Track count, Shuffle on, Repeat mode and Current chapter title.

────────────────────────────────
TIPS
────────────────────────────────

• Continue where they left off. Save Current time and Current track index on the On pause event, and feed them back as start_at and start_track next time.
  
• Decide what plays next. Use the On end of playlist event. It fires when the last track finishes and nothing is left — the player does not loop back to the first track on its own. Set repeat_mode to All if you want it to.
  
• For podcasts: set skip_seconds to 15 or 30, keep the speed control on, and turn shuffle and repeat off. Shuffle means nothing on an episode.
  
• For music: keep shuffle and repeat on, and hide the skip buttons if the row feels busy.
  
• A mini player at the bottom of a page: layout Bar, artwork_style Compact, show_queue off, in a floating group.
  
• Too many workflow runs? Raise time_update_interval. It controls both the On time update event and how often Current time is published.
  
• One player per page. The actions talk to the last one placed.
  
• Real waveforms: if your app has peak data, put it in waveform_peaks in any scale. Leave it empty and a waveform is generated from the track link.
  

────────────────────────────────
TESTING
────────────────────────────────

The browser preview runs React Native for Web, where the native audio engine does not exist. It falls back to a plain audio element, which is fine for checking layout, the waveform, the queue and chapters.

Playback itself, lock screen controls, background audio and the iPhone silent switch can only be tested in BubbleGo or a build.

📄 Full documentation:  https://wide-finch-c12.notion.site/Audio-Player-Documentation-3d561f4cca3a80d9a8a2f68dcc2e8b08?pvs=73