Skip to content

feat: books and podcasts play at 0.75x to 2x - #70

Open
hva314 wants to merge 17 commits into
BasilSkyWalk:mainfrom
hva314:feat/playback-speed
Open

hva314 wants to merge 17 commits into
BasilSkyWalk:mainfrom
hva314:feat/playback-speed

Conversation

@hva314

@hva314 hva314 commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Audiobooks and podcasts can now play at 0.75x, 1x, 1.25x, 1.5x, 1.75x or 2x, always keeping the voice's pitch. Music always plays at 1x.

What the listener sees

  • Settings → Sound → Book & podcast speed: 0.75x to 2x. The default is 1x.
  • Which files:
    • Files up to 64 kHz, which covers nearly every book and podcast, play at every speed.
    • 88.2 and 96 kHz files go up to 1.5x; choosing 1.75x or 2x plays them at 1.5x.
    • 176.4 and 192 kHz files always play at 1x.
  • Now Playing shows the speed the book actually plays at, first on the modes line ("1.5x · Repeat All"), for a book or podcast that isn't at 1x.
  • Changing the speed applies at once, from the current position, even while paused. The clock, seek bar, bookmarks and resume stay in the book's own time.
  • Equalizer: faster than 1x, it is off once the file's rate times the speed passes 96 kHz (for example a 96 kHz book at 1.25x). That is the same limit as at 1x.

There is no new key: on Now Playing, ≡ already opens Up Next (tap) and the Equalizer (hold).

How it works

docs/architecture.md → "Playback speed" has the full description, including the load limits, WSOLA parameters, where the equalizer runs, memory, and the queue rules.

  • src/dsp speed stage (speed, speed_fifo, stretch), shared by the device, the simulator and the host tests. It uses integers only, no heap and no .data, and the caller owns its 28.8 KB SpeedStage.
    • WSOLA: 40 ms sequence, 10 ms overlap, 15 ms seek, SAD search.
    • Above 48 kHz the three lengths keep their 48 kHz frame counts, so 96 kHz needs no more memory (20, 5 and 7.5 ms there).
    • speed_played_quarters is the only place that decides how fast a track plays. It never lets a track decode more than 144,000 frames a second.
  • HAL: hal_audio_set_speed(HalAudioSpeed). Speed is stored in quarters (3–8, 4 = 1x). position_ms stays track time at every speed.
  • Device audio engine (platform/device/logic/audio_engine.c):
    • The stage runs on core 0 at the source rate, before the equalizer and the ramp.
    • At 1x it is bypassed and the ring is bit for bit what it was.
    • Both paths share one copy_chunk, so each helper appears once in the code window.
    • At the end of a track the stage's tail drains before the next segment starts.
  • Board:
    • The stage lives in NOLOAD .high_ram, so it adds nothing to the loaded image.
    • A speed change restarts the stream from the current position at the next service call.
    • hal_audio_queue_next takes the new request first, then restarts if needed, so a track it replaces can't open again during the restart.
    • Core 1 stays at full clock above 1x.
    • Core 1 gets the equalizer curve again when a kept stream restarts, so a speed change switches its equalizer on or off.
  • Player:
    • Each track gets its own speed: books and podcasts the chosen one, music 1x. The speed is sent before every hal_audio_play.
    • The next track is queued gaplessly only when its speed matches the current one. Otherwise it starts when the current track ends.
    • Changing the speed never withdraws a gapless next track the HAL may already have opened.
    • When the next track changes after the device has already opened it (a speed change, Play next, Add to Up Next, shuffle or repeat in the last fraction of a second), the device restarts from the current position, so the new next track, or none, follows.
  • Settings: slot 22 (OPTION_SPOKEN_SPEED, byte 42), default 0 = 1x, so there is no version bump. Slot 23 stays free.
  • Strings and language packs: one new English string, "Book & podcast speed". The packs are rebuilt with tools/lang_pack.py; there are no translations yet, so other languages show the English text. The largest pack, uk.bin, is 12,027 of 12,288 B.
  • Simulator: uses the same stage and the same limits. The headless clock advances at the playing speed.

Size

Limit main (0.12.0) This PR
Code window free, device preset 1,848 B 120 B
Code window free, release preset 3,792 B 2,048 B
Resident tables free 460 B 424 B
.high_ram used 41,052 of 72,192 B 69,852 of 72,192 B

Measured with arm-none-eabi-gcc 14.2.1, which leaves about 460 B less room than the numbers in the review (2,308 B free in device on main). On that toolchain expect roughly 580 B free in device and 2,460 B in release.

The speed sources build with -Os in cross builds to fit the code window.

Changes since the review

  • feat: books and podcasts always keep their pitch, and the pitch setting is gone. Follows speed and its resampler cost about 1.5 KB. This frees slot 23 again.
  • perf: the audio engine's speed path is one pipeline again (−456 B). Checked against the old engine on 400 randomized runs of 4,000 operations each: the ring and every status field are byte-identical.
  • perf: the speed settings and the player's speed helpers take less room (−224 B), with new tests that a deferred song which starts is saved and that choosing a speed reaches the settings file.
  • perf: the time stretch takes less room with the same output (−796 B). The output is byte-identical to the previous version on 59,400 randomized cases, also under ASan and UBSan.
  • feat: books up to 96 kHz play at speed, with 88.2 and 96 kHz capped at 1.5x (+196 B). This is the decode limit and the equalizer rule above.
  • fix: a track queued near the end of another one plays the right track after it (−20 B). Found in a review of this branch. In the last ~0.3 s of a track:
    • a speed change could play the old next track;
    • withdrawing an opened next track (Play next with a book at another speed, shuffle, repeat) let it play under a token the player no longer follows, and the player then stayed silent in Playing.
    • Part of this already happens on main (repeat All to Off during the last track), and this fixes that too.
  • docs: the stage is 28,800 B, and slot 23 may still hold a pitch choice from earlier builds of this PR.

Tests

  • New: tests/dsp/test_speed.c and tests/sim/test_sim_speed.c.
  • Extended: test_audio_engine, test_player, test_spoken_word, test_settings, test_stores, test_settings_screens, test_app and test_now_playing_screen.
  • Coverage:
    • bypass, the 96 kHz limit and the 1.5x cap;
    • pitch kept at 44.1, 64, 88.2 and 96 kHz within the stage's memory;
    • the equalizer on at 48 kHz × 2 and off at 96 kHz × 1.5;
    • a 192 kHz book bit-identical to 1x;
    • stereo coherence and tails;
    • track-time position at 0.75x, 1.5x and 2x;
    • gapless hand-over at speed;
    • seeking at speed;
    • speed sent before every play;
    • a speed change while a gapless chapter is queued;
    • when the engine counts a next track as opened (from decoding until it plays, and while it waits for a rate change);
    • the Now Playing speed for 64, 96 and 192 kHz books.

ctest --preset dev: 178 of 180 pass, built with clang 21, clang-format 21, arm-none-eabi-gcc 14.2.1 and Python 3.12. The two failures also fail on main here and come from tool versions:

  • format: clang-format 21 against the project's version, in files this PR doesn't change. The changed lines are clean.
  • sort_fold_up_to_date: Python 3.12's unicodedata.

device_build, device_image_passes_the_updater_check, target_audit, no_comments, language_packs_up_to_date and tools_unit_tests pass.

Not yet tested on a player

ROADMAP.md marks this as sim, and docs/known-issues.md lists the limits. To check on hardware:

  • Diagnostics L and c at 2x for MP3, AAC (m4b), Opus and FLAC books, with the equalizer on and off
  • A 96 kHz FLAC book set to 2x: plays at 1.5x, Now Playing shows 1.5x, L and c
  • Chapter to chapter at 1.5x
  • A speed change mid-chapter and while paused
  • Book to song and song to book with the speed set (the gap should be short)
  • Book speed at 1.5x, a song in its last second, then Play next on a chapter: the chapter follows, with no silent stop

Try it

cmake --preset dev && cmake --build --preset dev && ctest --preset dev
./build/dev/platform/sim/echo_sim --card /path/with/Audiobooks --system-dir build/system
cmake --preset release && cmake --build --preset release

The release image is build/release/HIFIEC90.IMG.

The version number and release notes are unchanged, left for a release commit.

@BasilSkyWalk

Copy link
Copy Markdown
Owner

Thanks for this. The DSP work is careful: bypassed at 1x, the bounds and the Q14 math hold up, and the tests cover a lot. I haven't merged it yet for three reasons:

  1. Code space. feat: play .m4b audiobooks with embedded chapters #74, QOA support #49 and feat: seven more colour themes and four retro Now Playing faces #73 just landed. That leaves 2,308 bytes free in the code window for the device preset and 4,204 for release. This PR costs about 4,030 bytes, so the device build no longer fits. Could you find roughly 2 KB?
  2. Settings slot. feat: seven more colour themes and four retro Now Playing faces #73 took slot 21 (OPTION_NOW_PLAYING_FACE), so speed and pitch would move to 22 and 23. feat: seven more colour themes and four retro Now Playing faces #73 also shrank .high_ram to 72,192 bytes. Your 69,864 still fits, but only just.
  3. Hardware. Above 1x, core 1 runs at full clock and equalizes itself. A 96 kHz or higher FLAC book at 2x may underrun there. It would be good to hear how that behaves on a player.

A rebase onto current main with those changes would be great. I'll merge it once it fits.

hva314 and others added 17 commits November 11, 2026 23:51
…peed

Adds the HalAudioSpeed contract with store-only implementations, and a
fixed-point dsp module shared by the device engine, the simulator and the
host tests: a WSOLA time-stretch for sources up to 48 kHz and a 16-tap
polyphase resampler for everything else. Nothing uses it yet.

Co-Authored-By: Claude <noreply@anthropic.com>
…time

The engine pushes converted frames through the speed stage at the source
rate, before the whole-number upsampler, and runs the core 0 equalizer on
the stage's output so its cost follows the output rate. Each segment keeps
its speed, so the position stays in track time. A finished track drains
the stage before the next one opens, so its last words are heard and the
next segment starts after them. At normal speed nothing changes.

Co-Authored-By: Claude <noreply@anthropic.com>
The speed stage lives in High RAM beside the decode buffers, so it costs
nothing against the loaded-image limit. A new speed restarts the stream
from its current position at the next service, before a queued track is
replaced, or on resume, so a paused book never resumes at the old speed.
Faster than normal speed keeps the 200 MHz clock and gives core 1 its
full speed.

Co-Authored-By: Claude <noreply@anthropic.com>
Two option slots hold the book and podcast speed and pitch, with 0 as
normal speed and Keep pitch, so settings from 0.11 load unchanged. The
player sends each track's speed right before it plays, queues a next
track without a gap only at the same speed, and starts a deferred one
when the current track ends. A speed change never takes back a next
track the audio path may already have opened.

Co-Authored-By: Claude <noreply@anthropic.com>
…g shows it

Book & podcast speed and Book & podcast pitch join the Sound group, and
a change reaches the player at once. Now Playing puts the speed first on
the modes line, such as 1.5x, while a book or episode plays faster or
slower than normal. The language packs carry the new texts in English.

Co-Authored-By: Claude <noreply@anthropic.com>
The simulator runs the same speed stage as the player, with its SDL
stream left at the source rate, and lets a track's tail play out before
switching to the next. Headless runs move the virtual position by the
speed, so scripted runs stay deterministic.

Co-Authored-By: Claude <noreply@anthropic.com>
The user guide explains the two Sound rows and what the speed does to
times, bookmarks and the queue. The architecture notes record the HAL
contract, the player's per-track rule, the device stage, its memory and
clocks, and the filter and WSOLA parameters, which the code can't carry
as comments. Known issues lists what still needs a player to confirm.

Co-Authored-By: Claude <noreply@anthropic.com>
…tes never stretch

A seek or a resume after a long pause re-queued the next track the engine
had already opened, even when a newer request had replaced or cancelled
it, so the player could be handed a track it no longer expected. Keep
pitch also looped forever on a source rate below 25 Hz; it now needs at
least 4 kHz and resamples below that. Two engine tests now check what
they claim.

Co-Authored-By: Claude <noreply@anthropic.com>
…ails

The rescan takes the audio path away without telling the player, so a
failed scan left it waiting on a stopped track, and with a deferred next
track it would have started that one mid-episode. The player is now
released first, as for a USB session, so it stays paused where it was.
A test also pins that a speed change follows a hand-over the audio path
already made before queuing again.

Co-Authored-By: Claude <noreply@anthropic.com>
…, and the roadmap

Corrects the review's findings: the equalizer's place depends on the
codec, the 47 dB figure needs its band, the end-of-track silence is
longer at slow speeds, and the speed sources build at -Os. The roadmap
marks playback speed as working in the simulator.

Co-Authored-By: Claude <noreply@anthropic.com>
…ng is gone

The device image no longer fits once 0.12's changes landed, and Follows
speed with its resampler cost about 1.5 KB of the code window. Speed now
always keeps the voice's pitch, which frees settings slot 23 again, and
a book above 48 kHz plays at 1x. A settings file that chose Follows
speed still loads.

Co-Authored-By: Claude <noreply@anthropic.com>
…s less room

Speed added a second path through convert, equalize, ramp and write, so
the link kept two copies of each. Both paths now share one copy_chunk,
the track ends in one place, and the board keeps its speed in one
setting, which frees about 450 bytes of the code window. The ring is
byte for byte what it was, and the engine reports its state through an
accessor instead of copying its whole status.

Co-Authored-By: Claude <noreply@anthropic.com>
The speed labels live once in settings and the Now Playing badge reads
them, the stored order maps to quarters by swapping its first two
entries instead of a table, the player sends its speed from one helper,
and every Settings save hands the stored speed to the player instead of
each speed row doing it. Tests now pin that a deferred song which
starts is saved, and that choosing a speed reaches the settings file.

Co-Authored-By: Claude <noreply@anthropic.com>
The fifo appends and drops in one path each, the stage keeps its speed
and resets its fifo once, the crossfade is written once for both
channels, the search buffers share memory, and the first sequence runs
the normal search, which finds offset 0. Counters sit ahead of the
sample arrays so Thumb reaches them with short offsets, and
stretch_configure stays out of the -O2 engine. The output is byte for
byte the same on 59,400 randomized cases (rates, speeds, signals and
push/pull patterns), and the device image fits again.

Co-Authored-By: Claude <noreply@anthropic.com>
…t 1.5x

Some audiobooks come at 64 kHz or more, and they played at 1x. The time
stretch now runs up to 96 kHz in the same memory, its lengths keeping
their 48 kHz frame counts. A track never decodes more than 144,000
frames a second, three quarters of what a 192 kHz FLAC needs at 1x, so
88.2 and 96 kHz books go up to 1.5x and 176.4 and 192 kHz ones stay at
1x. The equalizer is off once rate times speed passes 96 kHz, the same
limit as at 1x, on core 1, in the engine and in the simulator; core 1
gets the curve again when a kept stream restarts, so a speed change
switches it. Now Playing shows the speed a book actually plays at.

Co-Authored-By: Claude <noreply@anthropic.com>
… after it

The player can withdraw or replace its next track at any moment (a speed
change, Play next, Add to Up Next, shuffle, repeat), but the device opens
the next track up to one ring before the current one ends (about 0.3 s at
44.1 kHz). It dropped an opened track only when a speed change restarted
the stream, and even then it restarted before taking the new request, so
the restart's prefill could open the old next track again.

In that last fraction of a second this went wrong in two ways:
- a speed change could play the old next track (a song at 2x, or the next
  chapter twice) and save the song's position as the book's resume point;
- withdrawing a next track without a speed change let it play under a
  token the player no longer follows, and the player then stayed in
  Playing, silent, with auto-off held off until Next or Previous.

hal_audio_queue_next now takes the new request first, and treats replacing
an opened next track as a restart from the current position, as a speed
change already was. follow_queue checks for itself that a next track still
waits, so the re-queue after a restart can't arm a track the restart's
prefill already opened. The code window gains 20 bytes.

Co-Authored-By: Claude <noreply@anthropic.com>
The stage shrank to 28,800 bytes when the pitch setting went. Test builds
of playback speed kept the pitch choice in slot 23, so a settings file one
of them saved last can still hold a 1 there.

Co-Authored-By: Claude <noreply@anthropic.com>
@hva314
hva314 force-pushed the feat/playback-speed branch from 48de298 to beec103 Compare November 12, 2026 06:58
@hva314

hva314 commented Nov 12, 2026

Copy link
Copy Markdown
Contributor Author

Thanks! Rebased onto 0.12.0. The changes are separate commits on top, so they're easy to follow.

  1. Size: it's down to ~1.7 KB from ~4 KB. I dropped the "Follows speed" mode and its resampler, so books always keep their pitch. I also trimmed the engine, settings and stretch, with the same output. Here device has 120 B free and release 2,048 B. My toolchain gives ~460 B less than yours, so you should see ~580 B and ~2.4 KB.
  2. Slot: speed is in slot 22 now, and 23 stays free. .high_ram is at 69,852 of 72,192.
  3. Hardware: a track never decodes more than 144k frames/s, which is ¾ of 192 kHz at 1x. So 64 kHz and below go up to 2x, 88.2/96 kHz max out at 1.5x, and 176.4/192 kHz stay at 1x. EQ turns off once rate × speed passes 96 kHz, same rule as at 1x. I haven't tried it on a player yet. I'll post the L/c numbers when I do.

Also fixed a race in hal_audio_queue_next. If the next track changed in the last ~0.3 s of a track, the player could get stuck in silence. It hits main too (repeat All → Off near the end of the last track). The fix saves 20 B and has a test.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants