Playlist Block: Add waveform playback controls by scruffian · Pull Request #75060 · WordPress/gutenberg

scruffian · 2026-01-29T16:15:26Z

What?

This PR extends the Playlist block's waveform player with:

Playlist navigation controls for previous track, next track, shuffle, and repeat.
Repeat modes that cycle from off, to repeat playlist, to repeat current track.
Repeat playlist behavior that advances to the next track that would play, including shuffled playback.
Repeat current track behavior that replays the active track when a track ends or when next is pressed.
Separate icons for repeat playlist and repeat current track, without the numeric repeat-one overlay.
A Tracklist setting for showing or hiding track lengths.
Hover styling for the waveform bars and refreshed playlist track styling.
Shared waveform helpers for time formatting, control setup, hover behavior, repeat/shuffle playback decisions, and cleanup.

It also updates the Playlist block attributes documentation and adds unit coverage for the new playlist and waveform utility behavior.

Why?

The Playlist block already uses a waveform player, but the player and track list need more of the controls and display options users expect from a playlist experience. These changes make it easier to navigate between tracks, randomize playback, repeat either the playlist or current track, and simplify the visible track metadata.

How?

Adds showTrackLength, showProgressBackground, and progressColor Playlist block attributes.
Passes the existing selected visualization style from the block style class into the editor and frontend waveform player.
Adds previous, next, shuffle, and repeat callbacks in both the editor component and frontend Interactivity API view.
Adds shared waveform utility support for formatting time, setting up playlist controls, applying hover colors, choosing repeat/shuffle playback actions, replaying the current track, and cleaning up listeners.
Adds repeat button state labels and mode-specific icons for repeat playlist and repeat current track.
Adds playlist track list classes and styles for hiding track lengths and improving active/hover track states.
Aligns focus styling across the custom waveform play and playlist control buttons.

Screenshots

Testing Instructions

Start the test environment if needed with npm run wp-env-test status and npm run wp-env-test start.
Build or run the editor assets.
Add a Playlist block with multiple audio tracks.
Confirm the waveform player appears and playback works.
Use previous and next controls to move between tracks.
Enable shuffle and confirm next/ended playback selects another track.
Enable repeat playlist and confirm ended/next playback advances to the next track that would play, wrapping as needed.
Enable repeat current track and confirm ended/next playback replays the current track.
Enable shuffle and repeat current track together and confirm ended/next playback still replays the current track.
Switch between the existing waveform block styles and confirm the visualization still updates.
Toggle the Tracklist track length setting and confirm durations hide/show.
Confirm track hover and active states render correctly in the editor and frontend.

Automated Tests

npm run test:unit packages/block-library/src/utils/test/waveform-utils.js packages/block-library/src/utils/test/waveform-player.js -- --runInBand
npm run test:unit packages/block-library/src/playlist/test/edit.js -- --runInBand
npm run lint:js -- packages/block-library/src/utils/waveform-utils.js packages/block-library/src/utils/waveform-player.js packages/block-library/src/utils/test/waveform-utils.js packages/block-library/src/utils/test/waveform-player.js packages/block-library/src/playlist/edit.js packages/block-library/src/playlist/view.js
npm run lint:css -- packages/block-library/src/playlist/style.scss
git diff --check

github-actions · 2026-01-29T16:27:33Z

Size Change: +8.8 kB (+0.11%)

Total Size: 7.73 MB

📦 View Changed

Filename	Size	Change
`build/modules/block-library/playlist/view.min.js`	19.2 kB	+2.38 kB (+14.18%)	⚠️
`build/scripts/block-library/index.min.js`	353 kB	+2.42 kB (+0.69%)
`build/styles/block-library/editor-rtl.css`	12.7 kB	+47 B (+0.37%)
`build/styles/block-library/editor-rtl.min.css`	10.4 kB	+45 B (+0.44%)
`build/styles/block-library/editor.css`	12.7 kB	+47 B (+0.37%)
`build/styles/block-library/editor.min.css`	10.4 kB	+46 B (+0.45%)
`build/styles/block-library/playlist-track/style-rtl.css`	927 B	+399 B (+75.57%)	🆘
`build/styles/block-library/playlist-track/style-rtl.min.css`	519 B	+25 B (+5.06%)	🔍
`build/styles/block-library/playlist-track/style.css`	926 B	+397 B (+75.05%)	🆘
`build/styles/block-library/playlist-track/style.min.css`	518 B	+25 B (+5.07%)	🔍
`build/styles/block-library/playlist/editor-rtl.css`	209 B	+103 B (+97.17%)	🆘
`build/styles/block-library/playlist/editor-rtl.min.css`	189 B	+95 B (+101.06%)	🆘
`build/styles/block-library/playlist/editor.css`	209 B	+103 B (+97.17%)	🆘
`build/styles/block-library/playlist/editor.min.css`	189 B	+95 B (+101.06%)	🆘
`build/styles/block-library/playlist/style-rtl.css`	2.5 kB	+352 B (+16.35%)	⚠️
`build/styles/block-library/playlist/style-rtl.min.css`	2.41 kB	+340 B (+16.45%)	⚠️
`build/styles/block-library/playlist/style.css`	2.51 kB	+354 B (+16.43%)	⚠️
`build/styles/block-library/playlist/style.min.css`	2.41 kB	+342 B (+16.54%)	⚠️
`build/styles/block-library/style-rtl.css`	22.6 kB	+306 B (+1.37%)
`build/styles/block-library/style-rtl.min.css`	19.1 kB	+286 B (+1.52%)
`build/styles/block-library/style.css`	22.7 kB	+305 B (+1.36%)
`build/styles/block-library/style.min.css`	19.1 kB	+285 B (+1.52%)

_{compressed-size-action}

github-actions · 2026-01-29T17:10:18Z

Flaky tests detected in 5d869fe.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29352899087
📝 Reported issues:

[Flaky Test] inserts a mention chip that survives saving the note #80226 in /test/e2e/specs/editor/various/block-notes.spec.js
[Flaky Test] should update the HTML only for the latest navigation #78835 in /test/e2e/specs/interactivity/router-navigate.spec.ts

Replace the createSvgIcon() DOM builder with inline SVG markup strings set via innerHTML on each control button. Simpler for static icons, and still iframe-safe (the button is created in the container's document, so innerHTML parses there). Verified the markup yields a queryable svg path so styleSvgIcons and the active-state fill still apply. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The shuffle and repeat controls are toggle buttons but only conveyed their on/off state visually via an is-active class, leaving it inaccessible to assistive technology. Make aria-pressed the single source of truth: set it from the initial shuffle/repeat state, flip it in the click handlers, and key the toggled-on styling off [aria-pressed="true"] instead of .is-active. Drop the is-active class entirely. Prev/next stay momentary actions with no aria-pressed. Export setupPlaylistControls and add unit tests covering the initial state, the prev/next absence of aria-pressed, and the toggle behavior. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The play button kept focus via a requestAnimationFrame refocus that let the library's container steal focus and then grabbed it back. Match the prev/shuffle/repeat/next controls instead: add a click listener that calls stopPropagation so the click never reaches the container's self-focus handler. stopPropagation (not stopImmediatePropagation) leaves the library's own togglePlay handler on the same element intact. Add unit tests asserting a play button click does not bubble to the container, and that cleanup removes the listener. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Tested in the editor: keyboard focus on the skip controls survives a track change without the restore machinery, so the restoreFocusRef / focusControl path is unnecessary. Remove it from both the editor component and initWaveformPlayer. Focus on every control (play/pause, prev, shuffle, repeat, next) is now preserved by a single mechanism: stopPropagation on each button's click so the library's container never steals focus. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

scruffian self-assigned this Jan 29, 2026

github-actions Bot added the [Package] Block library /packages/block-library label Jan 29, 2026

scruffian force-pushed the try/waveformplayer branch from d61612d to bf7970b Compare January 29, 2026 16:49

scruffian mentioned this pull request Feb 3, 2026

Add Block: Playlist #805

Closed

scruffian force-pushed the try/waveformplayer branch 2 times, most recently from 06722cc to 219fcef Compare February 3, 2026 10:21

scruffian changed the title ~~try waveformplayer~~ Playlist Block: Add WaveformPlayer visualization Feb 4, 2026

scruffian added [Type] Enhancement A suggestion for improvement. [Block] Playlist labels Feb 4, 2026

scruffian force-pushed the try/waveformplayer branch 2 times, most recently from cc09ee2 to cb693c9 Compare February 4, 2026 14:54

scruffian mentioned this pull request Feb 4, 2026

Playlist Block: Add WaveformPlayer visualization #75203

Merged

scruffian force-pushed the try/waveformplayer branch 3 times, most recently from 9502f73 to 4a2abf1 Compare February 13, 2026 14:15

scruffian changed the base branch from trunk to try/waveformplayer-simple February 13, 2026 14:17

scruffian changed the base branch from try/waveformplayer-simple to trunk February 13, 2026 14:18

scruffian force-pushed the try/waveformplayer branch from 4a2abf1 to 7601c4e Compare February 13, 2026 14:21

scruffian changed the base branch from trunk to try/waveformplayer-simple February 13, 2026 14:22

scruffian force-pushed the try/waveformplayer branch 3 times, most recently from 19c142f to 97d95c0 Compare February 13, 2026 15:14

scruffian changed the title ~~Playlist Block: Add WaveformPlayer visualization~~ Playlist Block: Add more WaveformPlayer options Feb 13, 2026

scruffian force-pushed the try/waveformplayer-simple branch 2 times, most recently from 997086d to 7deb4ae Compare February 19, 2026 12:19

scruffian force-pushed the try/waveformplayer-simple branch 3 times, most recently from fac2ce5 to d31f330 Compare February 26, 2026 11:11

scruffian and others added 29 commits July 15, 2026 11:37

Update playlist waveform colors live

fe9ab44

Fix playlist waveform lint failures

ebb2a47

Remove waveform hover color redraw

ac63e9d

Limit waveform focus restore to skip controls

59b92a3

Update playlist controls and repeat behavior

8ae6684

Refine playlist repeat and control alignment

ae795da

Fix playlist waveform playback edge cases

7746668

Test playlist repeat and shuffle behavior

44dbc32

Fix playlist track attributes test

fdc91d3

Add playlist repeat modes

f4cca10

Refine playlist repeat controls

0dfc444

Restore playlist track length setting

01e6192

Add repeat all icon string export

4271f05

Fix icons storybook library exports

ce8872b

Fix media upload CI timeouts

e36d25b

Fix playlist waveform follow-ups

8f66036

Reuse icon package strings for playlist controls

c692e6e

Split play button artwork from waveform PR

f1c7e39

Add playlist playback controls setting

80c3782

Refine playlist waveform controls

97cf29a

Align playlist waveform metadata

47e2ddd

Fix playlist CI failures

a4a5adc

Move playlist controls outside waveform player

0a8af00

Simplify playlist waveform player integration

aeedc99

Fix playlist waveform CI failures

56fdb7e

scruffian force-pushed the try/waveformplayer branch from 5d869fe to 56fdb7e Compare July 15, 2026 10:38

Navigation Menu

Repository navigation

Playlist Block: Add waveform playback controls - #75060

Playlist Block: Add waveform playback controls#75060
scruffian wants to merge 70 commits into
trunkfrom
try/waveformplayer

scruffian commented Jan 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jan 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jan 29, 2026 •

edited

Loading

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

scruffian commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Screenshots

Testing Instructions

Automated Tests

Uh oh!

github-actions Bot commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

scruffian commented Jan 29, 2026 •

edited

Loading

github-actions Bot commented Jan 29, 2026 •

edited

Loading

github-actions Bot commented Jan 29, 2026 •

edited

Loading