[feat] Add sample rate parameter to `st.audio_input` component #12272

sfc-gh-nbellante · 2025-08-19T20:50:18Z

Configurable audio sample rates for `st.audio_input`

Overview

Adds support for configurable audio sample rates in st.audio_input, letting apps pick recording quality per use case (e.g., 16 kHz for ASR, 48 kHz for music).

While I'm here, this PR also fixes #12446

Changes

Python API

sample_rate (optional) added to st.audio_input(...), default 16 kHz.
Validates against: 8000, 16000, 22050, 44100, 48000 Hz.
Raises StreamlitAPIException on invalid values.

Frontend

Media constraints: pass sampleRate: { ideal: targetSampleRate } to getUserMedia.
Guaranteed resampling: use OfflineAudioContext to convert to the exact target rate.
Why both? Devices may ignore ideal; resampling enforces consistency.

Technical details

Removed incorrect audioBitsPerSecond usage (bitrate ≠ sample rate).
Removed invalid audioContext option from RecordPlugin.
Pass constraints to startRecording() (not the plugin constructor).

Testing

Unit::
- Error handling (null/empty blobs, missing APIs)
- WebKit fallbacks
- Up/down-sampling across 6 rate pairs
- Channel configs: mono, stereo, 4-ch, 5.1
E2E: verifies sample-rate options render and work
Coverage: frontend ≈ 86%

Example usage

# Speech recognition optimized
audio_bytes = st.audio_input("Record speech", sample_rate=16000)

# High-quality music recording
audio_bytes = st.audio_input("Record music", sample_rate=48000)

# Default browser sample rate
audio_bytes = st.audio_input("Record audio", sample_rate=None)

Files changed

lib/streamlit/elements/widgets/audio_input.py — Python API
frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx — React updates
frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.ts — resampling
frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.test.ts — new tests
lib/tests/streamlit/elements/audio_input_test.py — Python tests
e2e_playwright/st_audio_input*.py — E2E coverage

Notes

sampleRate is an ideal getUserMedia constraint; actual device rate may differ.
Resampling ensures the output matches the requested rate across browsers/devices.

snyk-io · 2025-08-19T20:50:28Z

🎉 Snyk checks have passed. No issues have been found so far.

✅ security/snyk check is complete. No issues have been found. (View Details)

✅ license/snyk check is complete. No issues have been found. (View Details)

github-actions · 2025-08-19T20:50:39Z

✅ PR preview is ready!

Name	Link
📦 Wheel file	https://core-previews.s3-us-west-2.amazonaws.com/pr-12272/streamlit-1.49.1-py3-none-any.whl
🕹️ Preview app	pr-12272.streamlit.app (☁️ Deploy here if not accessible)

github-actions · 2025-08-19T21:04:11Z

📉 Frontend coverage change detected

The frontend unit test (vitest) coverage has decreased by 0.0900%

Current PR: 84.8500% (47319 lines, 7166 missed)
Latest develop: 84.9400% (47139 lines, 7099 missed)

💡 Consider adding more unit tests to maintain or improve coverage.

📊 View detailed coverage comparison

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx

lib/streamlit/elements/widgets/audio_input.py

e2e_playwright/st_audio_input_test.py

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx

frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.ts

e2e_playwright/st_audio_input.py

frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.test.ts

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx

e2e_playwright/st_audio_input_test.py

lib/streamlit/elements/widgets/audio_input.py

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx

e2e_playwright/st_audio_input_test.py

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx

frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.ts

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx

frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.ts

e2e_playwright/st_audio_input_test.py

…ion and recording start

…prove readability and avoid race conditions

…plugin setup for improved clarity and performance

…ing URL handling for improved functionality

…eletion handling, and improve plugin management

…andling, and enhance cleanup logic for improved clarity and performance

…and streamline logic for improved clarity

…dio permission issues

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx

frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.test.ts

frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.ts

sfc-gh-bnisco · 2025-09-10T17:43:13Z

frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.ts

+    arrayBuffer = await fileBlob.arrayBuffer()
+  } catch (error) {
+    LOG.error("Failed to read blob as ArrayBuffer", error)
+    void audioContext.close()


question: Should we await for the .close() to succeed before returning?

Hmm are you thinking perhaps it's only not an issue right now cause fast computer? I was thinking it works while not waiting for it to finish (and we no longer depend on it) so why make the user wait for it.

Those are good points! My original question was more towards the syntax code smell of using void vs await. I would expect to use await in most scenarios, and only use void when we really don't care about the side-effect. I see your perspective from your last comment, so I think this is fine in practice.

frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.ts

…g to prevent unnecessary re-renders. and setRecordingTime(formatTime(0))

lib/tests/streamlit/elements/audio_input_test.py

…av.ts Co-authored-by: Bob Nisco <[email protected]>

e2e_playwright/st_audio_input_test.py

Copilot

Pull Request Overview

Copilot reviewed 8 out of 12 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.ts:1

The global regex replacement /:/g will replace all colons in the timestamp, but ISO timestamps contain multiple colons (e.g., '2025-01-15T10:30:45'). This could result in malformed filenames. Consider using a more specific replacement or sanitizing the entire timestamp for filename safety.

/**

lib/tests/streamlit/elements/audio_input_test.py

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx

sfc-gh-bnisco

Thanks for the revisions!

RonaldAJ · 2025-09-24T07:15:43Z

Thanks for making this! I haven't had the time to test it, but reading bits and pieces of code I see the right digital signal processing terminology, and the usual of by one bug fix so commonly occurring in this type of work.

sfc-gh-nbellante added security-assessment-completed Security assessment has been completed for PR change:feature PR contains new feature or enhancement implementation impact:users PR changes affect end users labels Aug 19, 2025

sfc-gh-nbellante requested a review from Copilot August 19, 2025 20:54

This comment was marked as outdated.

Sign in to view

github-advanced-security bot found potential problems Aug 20, 2025

View reviewed changes

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx Fixed Show fixed Hide fixed

sfc-gh-nbellante changed the title ~~[feat] Add sample rate configuration to audio input component and tests~~ [feat] Add sample rate parameter to st.audio_input component Sep 3, 2025

sfc-gh-nbellante changed the title ~~[feat] Add sample rate parameter to st.audio_input component~~ [feat] Add sample rate parameter to st.audio_input component Sep 4, 2025

sfc-gh-nbellante requested a review from Copilot September 4, 2025 16:07

This comment was marked as outdated.

Sign in to view

sfc-gh-nbellante force-pushed the nico/audio-input-sample-rate branch from 1db321e to 1545062 Compare September 4, 2025 17:15

sfc-gh-nbellante requested a review from Copilot September 5, 2025 17:53

This comment was marked as outdated.

Sign in to view

sfc-gh-nbellante marked this pull request as ready for review September 5, 2025 18:30

sfc-gh-nbellante requested a review from a team as a code owner September 5, 2025 18:30

graphite-app bot reviewed Sep 5, 2025

View reviewed changes

lib/streamlit/elements/widgets/audio_input.py Show resolved Hide resolved

sfc-gh-bnisco reviewed Sep 5, 2025

View reviewed changes

graphite-app bot reviewed Sep 8, 2025

View reviewed changes

e2e_playwright/st_audio_input_test.py Show resolved Hide resolved

sfc-gh-nbellante force-pushed the nico/audio-input-sample-rate branch from aa9bbff to 60ec96a Compare September 9, 2025 17:44

graphite-app bot reviewed Sep 9, 2025

View reviewed changes

lib/streamlit/elements/widgets/audio_input.py Show resolved Hide resolved

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx Show resolved Hide resolved

e2e_playwright/st_audio_input_test.py Show resolved Hide resolved

e2e_playwright/st_audio_input_test.py Show resolved Hide resolved

graphite-app bot reviewed Sep 9, 2025

View reviewed changes

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx Show resolved Hide resolved

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx Outdated Show resolved Hide resolved

frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.ts Outdated Show resolved Hide resolved

graphite-app bot reviewed Sep 9, 2025

View reviewed changes

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx Outdated Show resolved Hide resolved

graphite-app bot reviewed Sep 9, 2025

View reviewed changes

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx Outdated Show resolved Hide resolved

graphite-app bot reviewed Sep 9, 2025

View reviewed changes

frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.ts Show resolved Hide resolved

frontend/lib/src/components/widgets/AudioInput/convertAudioToWav.ts Show resolved Hide resolved

graphite-app bot reviewed Sep 9, 2025

View reviewed changes

e2e_playwright/st_audio_input_test.py Show resolved Hide resolved

sfc-gh-nbellante mentioned this pull request Sep 9, 2025

[chore] Prefer optional chain #12482

Merged

sfc-gh-nbellante added 16 commits September 10, 2025 09:48

fixing the remount issue

f6efa83

getting it into a more workable state

67dc0bd

Refactor async handling in AudioInput: use async/await for file delet…

9c69a00

…ion and recording start

Refactor stopRecording logic: extract waitForRecordEnd function to im…

d83ff1f

…prove readability and avoid race conditions

Refactor AudioInput: streamline waveSurfer initialization and record …

54ecb2c

…plugin setup for improved clarity and performance

Refactor AudioInput: enhance waveSurfer options and streamline record…

eb977d6

…ing URL handling for improved functionality

Refactor handleClear function: convert to async, ensure proper file d…

5fca9f6

…eletion handling, and improve plugin management

Refactor AudioInput: remove redundant comments, streamline blob URL h…

7108f57

…andling, and enhance cleanup logic for improved clarity and performance

Refactor AudioInput and convertAudioToWav: remove redundant comments …

169fe08

…and streamline logic for improved clarity

more cleanup

fdca09d

Add Webkit skip marker for test_audio_input_re_recording due to CI au…

950121a

…dio permission issues

removing webkit fallbacks

734b959

fix minor bug with clipping at end of recording

c8bbfd1

dont throw

681d9d9

adding docstring

b000b28

let's keep it simple

02dbf67

sfc-gh-nbellante force-pushed the nico/audio-input-sample-rate branch from 90d11de to 02dbf67 Compare September 10, 2025 16:49

optional chain

ef9c73e

sfc-gh-bnisco reviewed Sep 10, 2025

View reviewed changes

stabilized via useCallback and passed as a dependency to stopRecordin…

7d9bb04

…g to prevent unnecessary re-renders. and setRecordingTime(formatTime(0))

graphite-app bot reviewed Sep 10, 2025

View reviewed changes

lib/tests/streamlit/elements/audio_input_test.py Show resolved Hide resolved

Update frontend/lib/src/components/widgets/AudioInput/convertAudioToW…

81a545a

…av.ts Co-authored-by: Bob Nisco <[email protected]>

graphite-app bot reviewed Sep 10, 2025

View reviewed changes

e2e_playwright/st_audio_input_test.py Show resolved Hide resolved

sfc-gh-bnisco requested a review from Copilot September 10, 2025 22:40

Copilot AI reviewed Sep 10, 2025

View reviewed changes

lib/tests/streamlit/elements/audio_input_test.py Show resolved Hide resolved

frontend/lib/src/components/widgets/AudioInput/AudioInput.tsx Show resolved Hide resolved

sfc-gh-bnisco approved these changes Sep 10, 2025

View reviewed changes

sfc-gh-nbellante merged commit b502b3a into develop Sep 10, 2025
38 checks passed

sfc-gh-nbellante deleted the nico/audio-input-sample-rate branch September 10, 2025 22:50

jrieke mentioned this pull request Sep 23, 2025

Control over sampling frequency in st.audio_input and st.audio #9800

Closed

2 tasks

[feat] Add sample rate parameter to st.audio_input component #12272

[feat] Add sample rate parameter to st.audio_input component #12272

Uh oh!

Conversation

sfc-gh-nbellante commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Configurable audio sample rates for st.audio_input

Overview

Changes

Python API

Frontend

Technical details

Testing

Example usage

Files changed

Uh oh!

snyk-io bot commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎉 Snyk checks have passed. No issues have been found so far.

Uh oh!

github-actions bot commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ PR preview is ready!

Uh oh!

This comment was marked as outdated.

Uh oh!

github-actions bot commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📉 Frontend coverage change detected

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sfc-gh-bnisco Sep 10, 2025

Choose a reason for hiding this comment

Uh oh!

sfc-gh-nbellante Sep 10, 2025

Choose a reason for hiding this comment

Uh oh!

sfc-gh-bnisco Sep 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

[feat] Add sample rate parameter to `st.audio_input` component #12272

[feat] Add sample rate parameter to `st.audio_input` component #12272

sfc-gh-nbellante commented Aug 19, 2025 •

edited

Loading

Configurable audio sample rates for `st.audio_input`

snyk-io bot commented Aug 19, 2025 •

edited

Loading

github-actions bot commented Aug 19, 2025 •

edited

Loading

github-actions bot commented Aug 19, 2025 •

edited

Loading