# Streamlit Audio Stream Player
Beautiful audio stream player component for Streamlit with frequency visualization and animated state transitions, inspired by ElevenLabs UI design.
## Installation
```bash
pip install streamlit-audio-stream-player
```
## Features
- 🎵 **Two Visualization Modes**: Choose between Bar and Orb visualizers
- 🎨 **Customizable Colors**: Full control over colors and themes
- 🔄 **Auto State Transitions**: Automatic visualization based on audio playback
- 📊 **Real-time Frequency Analysis**: Dynamic visualization of audio frequencies
- 🌐 **Multiple Data Formats**: Support for URLs, files, bytes, and more
## Quick Start
### Basic Usage with URL
```python
import streamlit as st
from streamlit_audio_stream_player import audio_bar, audio_orb
st.title("🎵 Audio Stream Player")
# Bar visualizer
audio_bar(
data="https://stream.radioparadise.com/mp3-128",
key="audio_player"
)
# Orb visualizer
audio_orb(
data="https://stream.radioparadise.com/mp3-128",
key="orb_player"
)
```
## Visualization Modes
### Bar Visualizer
The traditional bar visualizer with animated frequency bars:
```python
from streamlit_audio_stream_player import audio_bar
audio_bar(
data="audio.mp3",
prime_color="#3b82f6",
second_color="#f1f5f9",
key="bar_player"
)
```
**States:**
- `thinking`: Audio loading (pulsing animation)
- `speaking`: Audio playing (frequency visualization)
- `initializing`: Audio ended (bars reset)
### Orb Visualizer
Animated blob/orb visualization with morphing shapes:
```python
from streamlit_audio_stream_player import audio_orb
audio_orb(
data="audio.mp3",
prime_color="#CADCFC",
second_color="#A0B9D1",
seed=1000,
key="orb_player"
)
```
**States:**
- `listening`: Slow morphing - 還沒獲取到首包音檔 (audio loading)
- `talking`: Fast morphing - 播放使用中 (audio playing)
- `idle`: Very slow morphing - 播放完畢 (audio ended)
**Parameters:**
- `prime_color`: First gradient color
- `second_color`: Second gradient color
- `seed`: Random seed for blob shape (different seeds = different shapes)
### Custom Colors
Customize the visualizer appearance with color parameters:
```python
# Bar visualizer: Red bars with dark background
audio_bar(
data="https://stream.radioparadise.com/mp3-128",
prime_color="#ff6b6b",
second_color="#1a1a2e",
key="red_player"
)
# Orb visualizer: Warm gradient
audio_orb(
data="https://stream.radioparadise.com/mp3-128",
prime_color="#F6E7D8",
second_color="#E0CFC2",
key="warm_orb"
)
# Orb visualizer: Purple gradient with custom shape
audio_orb(
data="https://stream.radioparadise.com/mp3-128",
prime_color="#E9D5FF",
second_color="#C084FC",
seed=2000,
key="purple_orb"
)
```
### Supported Data Formats
Both `audio_bar` and `audio_orb` accept multiple data formats:
```python
from pathlib import Path
from io import BytesIO
# 1. URL (streaming)
audio_bar(data="https://example.com/audio.mp3")
# 2. File path (string)
audio_bar(data="/path/to/audio.mp3")
# 3. Path object
audio_orb(data=Path("audio.mp3"))
# 4. Raw bytes
with open("audio.mp3", "rb") as f:
audio_bytes = f.read()
audio_bar(data=audio_bytes)
# 5. BytesIO
byte_io = BytesIO(audio_bytes)
audio_orb(data=byte_io)
```
### Complete Example
```python
import streamlit as st
from streamlit_audio_stream_player import audio_bar, audio_orb
st.title("🎵 Audio Stream Player Test")
# Session state
if 'play_count' not in st.session_state:
st.session_state.play_count = 0
# Audio stream options
stream_options = {
"Radio Paradise (MP3)": "https://stream.radioparadise.com/mp3-128",
"BBC World Service": "https://stream.live.vc.bbcmedia.co.uk/bbc_world_service",
"Custom URL": "custom"
}
selected_stream = st.selectbox("Select Audio Stream", list(stream_options.keys()))
if selected_stream == "Custom URL":
stream_url = st.text_input("Enter Audio Stream URL", value="https://stream.radioparadise.com/mp3-128")
else:
stream_url = stream_options[selected_stream]
# Visualization mode
mode = st.radio("Visualization Mode", ["bar", "orb"], horizontal=True)
st.info(f"🎧 Current Audio Stream: {stream_url}")
# Display audio stream player
if stream_url:
if mode == "orb":
audio_orb(
data=stream_url,
prime_color="#CADCFC",
second_color="#A0B9D1",
key=f"player_{st.session_state.play_count}"
)
else:
audio_bar(
data=stream_url,
key=f"player_{st.session_state.play_count}"
)
st.markdown("---")
st.caption("💡 Tip: If you don't hear sound, check the browser console (F12) for error messages and verify the audio stream URL is valid.")
```
## API Reference
### `audio_bar(data, key=None, prime_color="#3b82f6", second_color="#f1f5f9")`
Display an audio player with bar visualizer.
**Parameters:**
- `data` (str | Path | bytes | BytesIO | file): Audio data in various formats
- `key` (str | None): Unique component key
- `prime_color` (str): Bar color (default: `"#3b82f6"`)
- `second_color` (str): Background color (default: `"#f1f5f9"`)
**Returns:**
- `str`: Current state of the component
### `audio_orb(data, key=None, prime_color="#CADCFC", second_color="#A0B9D1", seed=1000)`
Display an audio player with animated orb visualizer.
**Parameters:**
- `data` (str | Path | bytes | BytesIO | file): Audio data in various formats
- `key` (str | None): Unique component key
- `prime_color` (str): First gradient color (default: `"#CADCFC"`)
- `second_color` (str): Second gradient color (default: `"#A0B9D1"`)
- `seed` (int): Random seed for orb shape (default: `1000`)
**Returns:**
- `str`: Current state of the component
> ⚠️ **Browser Compatibility Warning**: Safari may have issues with audio streaming due to CORS restrictions. For best results, use **Chrome** or **Firefox**.
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/bensonbs/streamlit-audio-stream-player",
"name": "streamlit-audio-stream-player",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "streamlit, audio, visualizer, frequency, component",
"author": "Benson Sung",
"author_email": "Benson Sung <benson.bs.sung@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/86/c7/2e047e939553f583aba25821b12cb10e46dec5e9c0c6ed69f63ad21c35b2/streamlit_audio_stream_player-0.2.2.tar.gz",
"platform": null,
"description": "# Streamlit Audio Stream Player\n\nBeautiful audio stream player component for Streamlit with frequency visualization and animated state transitions, inspired by ElevenLabs UI design.\n\n\n\n\n\n\n## Installation\n\n```bash\npip install streamlit-audio-stream-player\n```\n\n## Features\n\n- \ud83c\udfb5 **Two Visualization Modes**: Choose between Bar and Orb visualizers\n- \ud83c\udfa8 **Customizable Colors**: Full control over colors and themes\n- \ud83d\udd04 **Auto State Transitions**: Automatic visualization based on audio playback\n- \ud83d\udcca **Real-time Frequency Analysis**: Dynamic visualization of audio frequencies\n- \ud83c\udf10 **Multiple Data Formats**: Support for URLs, files, bytes, and more\n\n## Quick Start\n\n### Basic Usage with URL\n\n```python\nimport streamlit as st\nfrom streamlit_audio_stream_player import audio_bar, audio_orb\n\nst.title(\"\ud83c\udfb5 Audio Stream Player\")\n\n# Bar visualizer\naudio_bar(\n data=\"https://stream.radioparadise.com/mp3-128\",\n key=\"audio_player\"\n)\n\n# Orb visualizer\naudio_orb(\n data=\"https://stream.radioparadise.com/mp3-128\",\n key=\"orb_player\"\n)\n```\n\n## Visualization Modes\n\n### Bar Visualizer\n\nThe traditional bar visualizer with animated frequency bars:\n\n```python\nfrom streamlit_audio_stream_player import audio_bar\n\naudio_bar(\n data=\"audio.mp3\",\n prime_color=\"#3b82f6\",\n second_color=\"#f1f5f9\",\n key=\"bar_player\"\n)\n```\n\n**States:**\n- `thinking`: Audio loading (pulsing animation)\n- `speaking`: Audio playing (frequency visualization)\n- `initializing`: Audio ended (bars reset)\n\n### Orb Visualizer\n\nAnimated blob/orb visualization with morphing shapes:\n\n```python\nfrom streamlit_audio_stream_player import audio_orb\n\naudio_orb(\n data=\"audio.mp3\",\n prime_color=\"#CADCFC\",\n second_color=\"#A0B9D1\",\n seed=1000,\n key=\"orb_player\"\n)\n```\n\n**States:**\n- `listening`: Slow morphing - \u9084\u6c92\u7372\u53d6\u5230\u9996\u5305\u97f3\u6a94 (audio loading)\n- `talking`: Fast morphing - \u64ad\u653e\u4f7f\u7528\u4e2d (audio playing)\n- `idle`: Very slow morphing - \u64ad\u653e\u5b8c\u7562 (audio ended)\n\n**Parameters:**\n- `prime_color`: First gradient color\n- `second_color`: Second gradient color\n- `seed`: Random seed for blob shape (different seeds = different shapes)\n\n### Custom Colors\n\nCustomize the visualizer appearance with color parameters:\n\n```python\n# Bar visualizer: Red bars with dark background\naudio_bar(\n data=\"https://stream.radioparadise.com/mp3-128\",\n prime_color=\"#ff6b6b\",\n second_color=\"#1a1a2e\",\n key=\"red_player\"\n)\n\n# Orb visualizer: Warm gradient\naudio_orb(\n data=\"https://stream.radioparadise.com/mp3-128\",\n prime_color=\"#F6E7D8\",\n second_color=\"#E0CFC2\",\n key=\"warm_orb\"\n)\n\n# Orb visualizer: Purple gradient with custom shape\naudio_orb(\n data=\"https://stream.radioparadise.com/mp3-128\",\n prime_color=\"#E9D5FF\",\n second_color=\"#C084FC\",\n seed=2000,\n key=\"purple_orb\"\n)\n```\n\n### Supported Data Formats\n\nBoth `audio_bar` and `audio_orb` accept multiple data formats:\n\n```python\nfrom pathlib import Path\nfrom io import BytesIO\n\n# 1. URL (streaming)\naudio_bar(data=\"https://example.com/audio.mp3\")\n\n# 2. File path (string)\naudio_bar(data=\"/path/to/audio.mp3\")\n\n# 3. Path object\naudio_orb(data=Path(\"audio.mp3\"))\n\n# 4. Raw bytes\nwith open(\"audio.mp3\", \"rb\") as f:\n audio_bytes = f.read()\naudio_bar(data=audio_bytes)\n\n# 5. BytesIO\nbyte_io = BytesIO(audio_bytes)\naudio_orb(data=byte_io)\n```\n\n### Complete Example\n\n```python\nimport streamlit as st\nfrom streamlit_audio_stream_player import audio_bar, audio_orb\n\nst.title(\"\ud83c\udfb5 Audio Stream Player Test\")\n\n# Session state\nif 'play_count' not in st.session_state:\n st.session_state.play_count = 0\n\n# Audio stream options\nstream_options = {\n \"Radio Paradise (MP3)\": \"https://stream.radioparadise.com/mp3-128\",\n \"BBC World Service\": \"https://stream.live.vc.bbcmedia.co.uk/bbc_world_service\",\n \"Custom URL\": \"custom\"\n}\n\nselected_stream = st.selectbox(\"Select Audio Stream\", list(stream_options.keys()))\n\nif selected_stream == \"Custom URL\":\n stream_url = st.text_input(\"Enter Audio Stream URL\", value=\"https://stream.radioparadise.com/mp3-128\")\nelse:\n stream_url = stream_options[selected_stream]\n\n# Visualization mode\nmode = st.radio(\"Visualization Mode\", [\"bar\", \"orb\"], horizontal=True)\n\nst.info(f\"\ud83c\udfa7 Current Audio Stream: {stream_url}\")\n\n# Display audio stream player\nif stream_url:\n if mode == \"orb\":\n audio_orb(\n data=stream_url,\n prime_color=\"#CADCFC\",\n second_color=\"#A0B9D1\",\n key=f\"player_{st.session_state.play_count}\"\n )\n else:\n audio_bar(\n data=stream_url,\n key=f\"player_{st.session_state.play_count}\"\n )\n \nst.markdown(\"---\")\nst.caption(\"\ud83d\udca1 Tip: If you don't hear sound, check the browser console (F12) for error messages and verify the audio stream URL is valid.\")\n```\n\n## API Reference\n\n### `audio_bar(data, key=None, prime_color=\"#3b82f6\", second_color=\"#f1f5f9\")`\n\nDisplay an audio player with bar visualizer.\n\n**Parameters:**\n- `data` (str | Path | bytes | BytesIO | file): Audio data in various formats\n- `key` (str | None): Unique component key\n- `prime_color` (str): Bar color (default: `\"#3b82f6\"`)\n- `second_color` (str): Background color (default: `\"#f1f5f9\"`)\n\n**Returns:**\n- `str`: Current state of the component\n\n### `audio_orb(data, key=None, prime_color=\"#CADCFC\", second_color=\"#A0B9D1\", seed=1000)`\n\nDisplay an audio player with animated orb visualizer.\n\n**Parameters:**\n- `data` (str | Path | bytes | BytesIO | file): Audio data in various formats\n- `key` (str | None): Unique component key\n- `prime_color` (str): First gradient color (default: `\"#CADCFC\"`)\n- `second_color` (str): Second gradient color (default: `\"#A0B9D1\"`)\n- `seed` (int): Random seed for orb shape (default: `1000`)\n\n**Returns:**\n- `str`: Current state of the component\n\n> \u26a0\ufe0f **Browser Compatibility Warning**: Safari may have issues with audio streaming due to CORS restrictions. For best results, use **Chrome** or **Firefox**.\n\n## License\n\nMIT\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Beautiful audio stream player component for Streamlit with frequency visualization and state animations",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/bensonbs/streamlit-audio-stream-player",
"Issues": "https://github.com/bensonbs/streamlit-audio-stream-player/issues",
"Repository": "https://github.com/bensonbs/streamlit-audio-stream-player"
},
"split_keywords": [
"streamlit",
" audio",
" visualizer",
" frequency",
" component"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dd0ec7d53fd576f18211b0e1aafc7207a27638209fe52b697ff4787649434657",
"md5": "17edc7716e741334b6ca9f7a860f72a8",
"sha256": "a64dadf1e9dbaef1ca47366a6fd902ec044ca9ed09fe2b58c5ecd7ef8edfe14b"
},
"downloads": -1,
"filename": "streamlit_audio_stream_player-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "17edc7716e741334b6ca9f7a860f72a8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 381080,
"upload_time": "2025-10-11T10:36:54",
"upload_time_iso_8601": "2025-10-11T10:36:54.950680Z",
"url": "https://files.pythonhosted.org/packages/dd/0e/c7d53fd576f18211b0e1aafc7207a27638209fe52b697ff4787649434657/streamlit_audio_stream_player-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "86c72e047e939553f583aba25821b12cb10e46dec5e9c0c6ed69f63ad21c35b2",
"md5": "c3ccdebbb5df5d1f83eb15e7efe20ff8",
"sha256": "3cedc8de852d94caee146d6c5143a01779b1949f768145d143a8565218c79424"
},
"downloads": -1,
"filename": "streamlit_audio_stream_player-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "c3ccdebbb5df5d1f83eb15e7efe20ff8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 2151396,
"upload_time": "2025-10-11T10:36:58",
"upload_time_iso_8601": "2025-10-11T10:36:58.846830Z",
"url": "https://files.pythonhosted.org/packages/86/c7/2e047e939553f583aba25821b12cb10e46dec5e9c0c6ed69f63ad21c35b2/streamlit_audio_stream_player-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 10:36:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bensonbs",
"github_project": "streamlit-audio-stream-player",
"github_not_found": true,
"lcname": "streamlit-audio-stream-player"
}
JSON
