# Streamlit Real-time Audio
A Streamlit custom component for real-time voice conversations with OpenAI's GPT using WebRTC for low-latency audio streaming.
## Features
- π€ **Real-time Audio**: Low-latency audio streaming using WebRTC
- π€ **OpenAI Integration**: Direct integration with OpenAI's Real-time API
- π¬ **Live Transcription**: Real-time transcription of both user and AI speech
- βΈοΈ **Conversation Control**: Start, pause, resume, and stop conversations
- ποΈ **Configurable**: Customizable voice, instructions, and AI parameters
- π **Full Transcript**: Complete conversation history with timestamps
## Installation
```bash
pip install streamlit-realtime-audio
```
## Quick Start
```python
import streamlit as st
from st_realtime_audio import realtime_audio_conversation
st.title("AI Voice Assistant")
# Get API key from user
api_key = st.text_input("OpenAI API Key", type="password")
if api_key:
# Create the real-time audio conversation
result = realtime_audio_conversation(
api_key=api_key,
instructions="You are a helpful AI assistant. Keep responses concise.",
voice="alloy"
)
# Display conversation status
st.write(f"Status: {result['status']}")
# Show any errors
if result['error']:
st.error(result['error'])
# Display transcript
for message in result['transcript']:
if message['type'] == 'user':
st.chat_message("user").write(message['content'])
else:
st.chat_message("assistant").write(message['content'])
```
## Usage
### Basic Parameters
- **`api_key`** (str, required): OpenAI API key for authentication
- **`voice`** (str, default="alloy"): Voice for TTS. Options: "alloy", "echo", "fable", "onyx", "nova", "shimmer"
- **`instructions`** (str): System instructions for the AI
- **`temperature`** (float, default=0.8): AI response randomness (0.0-2.0)
- **`auto_start`** (bool, default=False): Whether to automatically start the conversation
### Advanced Example
```python
import streamlit as st
from st_realtime_audio import realtime_audio_conversation
st.set_page_config(page_title="Advanced AI Assistant", layout="wide")
col1, col2 = st.columns([3, 1])
with col2:
st.header("Settings")
api_key = st.text_input("API Key", type="password")
voice = st.selectbox("Voice", ["alloy", "echo", "fable", "onyx", "nova", "shimmer"])
temperature = st.slider("Temperature", 0.0, 2.0, 0.8)
instructions = st.text_area(
"Instructions",
"You are a helpful AI assistant.",
height=100
)
with col1:
st.header("Conversation")
if api_key:
conversation = realtime_audio_conversation(
api_key=api_key,
voice=voice,
instructions=instructions,
temperature=temperature,
turn_detection_threshold=0.5,
key="advanced_conversation"
)
# Handle the conversation result
if conversation['error']:
st.error(conversation['error'])
# Display metrics
col_a, col_b, col_c = st.columns(3)
with col_a:
st.metric("Status", conversation['status'])
with col_b:
st.metric("Messages", len(conversation['transcript']))
with col_c:
recording = "π΄" if conversation['is_recording'] else "βͺ"
st.metric("Recording", recording)
```
## Return Value
The component returns a dictionary with conversation state:
```python
{
"transcript": [
{
"id": "unique_message_id",
"type": "user" | "assistant",
"content": "Message content",
"timestamp": 1640995200000,
"status": "completed" | "in_progress"
}
],
"status": "idle" | "connecting" | "connected" | "recording" | "speaking" | "error",
"error": "Error message" | None,
"session_id": "unique_session_id" | None,
"connection_state": "new" | "connecting" | "connected" | "disconnected" | "failed" | "closed",
"is_recording": bool,
"is_paused": bool
}
```
## Requirements
- Python 3.9+
- Streamlit >= 1.28.0
- OpenAI API key
- HTTPS connection (required for WebRTC)
- Microphone access
## Browser Support
- Chrome, Firefox, Safari, Edge (latest versions)
- HTTPS required for WebRTC functionality
- Microphone permissions required
## Troubleshooting
### Common Issues
**Microphone Access Denied**
- Ensure you're using HTTPS
- Check browser permissions
- Try refreshing the page
**Connection Failed**
- Verify your OpenAI API key
- Check internet connection
- Ensure firewall isn't blocking WebRTC
**No Audio Playback**
- Check system audio settings
- Try different browsers
- Verify speakers/headphones are working
## Development
For development setup and contributing, see the [GitHub repository](https://github.com/bronsonhill/streamlit-realtime-audio).
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/bronsonhill/streamlit-realtime-audio",
"name": "streamlit-realtime-audio",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "streamlit, component, webrtc, openai, realtime, audio",
"author": "Bronson Hill",
"author_email": "bronson.hill@yahoo.com.au",
"download_url": "https://files.pythonhosted.org/packages/83/d9/2829ca11e848288a153a9e5a923a74cfd30e55c5b7b8a531cc0b2c264871/streamlit_realtime_audio-0.0.7.tar.gz",
"platform": null,
"description": "# Streamlit Real-time Audio\n\nA Streamlit custom component for real-time voice conversations with OpenAI's GPT using WebRTC for low-latency audio streaming.\n\n## Features\n\n- \ud83c\udfa4 **Real-time Audio**: Low-latency audio streaming using WebRTC\n- \ud83e\udd16 **OpenAI Integration**: Direct integration with OpenAI's Real-time API\n- \ud83d\udcac **Live Transcription**: Real-time transcription of both user and AI speech\n- \u23f8\ufe0f **Conversation Control**: Start, pause, resume, and stop conversations\n- \ud83c\udf9b\ufe0f **Configurable**: Customizable voice, instructions, and AI parameters\n- \ud83d\udcdd **Full Transcript**: Complete conversation history with timestamps\n\n## Installation\n\n```bash\npip install streamlit-realtime-audio\n```\n\n## Quick Start\n\n```python\nimport streamlit as st\nfrom st_realtime_audio import realtime_audio_conversation\n\nst.title(\"AI Voice Assistant\")\n\n# Get API key from user\napi_key = st.text_input(\"OpenAI API Key\", type=\"password\")\n\nif api_key:\n # Create the real-time audio conversation\n result = realtime_audio_conversation(\n api_key=api_key,\n instructions=\"You are a helpful AI assistant. Keep responses concise.\",\n voice=\"alloy\"\n )\n \n # Display conversation status\n st.write(f\"Status: {result['status']}\")\n \n # Show any errors\n if result['error']:\n st.error(result['error'])\n \n # Display transcript\n for message in result['transcript']:\n if message['type'] == 'user':\n st.chat_message(\"user\").write(message['content'])\n else:\n st.chat_message(\"assistant\").write(message['content'])\n```\n\n## Usage\n\n### Basic Parameters\n\n- **`api_key`** (str, required): OpenAI API key for authentication\n- **`voice`** (str, default=\"alloy\"): Voice for TTS. Options: \"alloy\", \"echo\", \"fable\", \"onyx\", \"nova\", \"shimmer\"\n- **`instructions`** (str): System instructions for the AI\n- **`temperature`** (float, default=0.8): AI response randomness (0.0-2.0)\n- **`auto_start`** (bool, default=False): Whether to automatically start the conversation\n\n### Advanced Example\n\n```python\nimport streamlit as st\nfrom st_realtime_audio import realtime_audio_conversation\n\nst.set_page_config(page_title=\"Advanced AI Assistant\", layout=\"wide\")\n\ncol1, col2 = st.columns([3, 1])\n\nwith col2:\n st.header(\"Settings\")\n api_key = st.text_input(\"API Key\", type=\"password\")\n voice = st.selectbox(\"Voice\", [\"alloy\", \"echo\", \"fable\", \"onyx\", \"nova\", \"shimmer\"])\n temperature = st.slider(\"Temperature\", 0.0, 2.0, 0.8)\n instructions = st.text_area(\n \"Instructions\", \n \"You are a helpful AI assistant.\",\n height=100\n )\n\nwith col1:\n st.header(\"Conversation\")\n \n if api_key:\n conversation = realtime_audio_conversation(\n api_key=api_key,\n voice=voice,\n instructions=instructions,\n temperature=temperature,\n turn_detection_threshold=0.5,\n key=\"advanced_conversation\"\n )\n \n # Handle the conversation result\n if conversation['error']:\n st.error(conversation['error'])\n \n # Display metrics\n col_a, col_b, col_c = st.columns(3)\n with col_a:\n st.metric(\"Status\", conversation['status'])\n with col_b:\n st.metric(\"Messages\", len(conversation['transcript']))\n with col_c:\n recording = \"\ud83d\udd34\" if conversation['is_recording'] else \"\u26aa\"\n st.metric(\"Recording\", recording)\n```\n\n## Return Value\n\nThe component returns a dictionary with conversation state:\n\n```python\n{\n \"transcript\": [\n {\n \"id\": \"unique_message_id\",\n \"type\": \"user\" | \"assistant\", \n \"content\": \"Message content\",\n \"timestamp\": 1640995200000,\n \"status\": \"completed\" | \"in_progress\"\n }\n ],\n \"status\": \"idle\" | \"connecting\" | \"connected\" | \"recording\" | \"speaking\" | \"error\",\n \"error\": \"Error message\" | None,\n \"session_id\": \"unique_session_id\" | None,\n \"connection_state\": \"new\" | \"connecting\" | \"connected\" | \"disconnected\" | \"failed\" | \"closed\",\n \"is_recording\": bool,\n \"is_paused\": bool\n}\n```\n\n## Requirements\n\n- Python 3.9+\n- Streamlit >= 1.28.0\n- OpenAI API key\n- HTTPS connection (required for WebRTC)\n- Microphone access\n\n## Browser Support\n\n- Chrome, Firefox, Safari, Edge (latest versions)\n- HTTPS required for WebRTC functionality\n- Microphone permissions required\n\n## Troubleshooting\n\n### Common Issues\n\n**Microphone Access Denied**\n- Ensure you're using HTTPS\n- Check browser permissions\n- Try refreshing the page\n\n**Connection Failed**\n- Verify your OpenAI API key\n- Check internet connection\n- Ensure firewall isn't blocking WebRTC\n\n**No Audio Playback**\n- Check system audio settings\n- Try different browsers\n- Verify speakers/headphones are working\n\n## Development\n\nFor development setup and contributing, see the [GitHub repository](https://github.com/bronsonhill/streamlit-realtime-audio).\n\n## License\n\nMIT License - see LICENSE file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Streamlit component for real-time audio conversation with OpenAI using WebRTC",
"version": "0.0.7",
"project_urls": {
"Homepage": "https://github.com/bronsonhill/streamlit-realtime-audio"
},
"split_keywords": [
"streamlit",
" component",
" webrtc",
" openai",
" realtime",
" audio"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d909a97234056db2b07b38f1f25e180c67ef9168903f3823171c8ef98c4381be",
"md5": "8ccf089c28c06d04dbbce20c52177993",
"sha256": "776b7eee0b80fda704cb8010d4dc098641801822b37753d1404df94eddba8a43"
},
"downloads": -1,
"filename": "streamlit_realtime_audio-0.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8ccf089c28c06d04dbbce20c52177993",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 105662,
"upload_time": "2025-07-18T02:29:14",
"upload_time_iso_8601": "2025-07-18T02:29:14.531705Z",
"url": "https://files.pythonhosted.org/packages/d9/09/a97234056db2b07b38f1f25e180c67ef9168903f3823171c8ef98c4381be/streamlit_realtime_audio-0.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "83d92829ca11e848288a153a9e5a923a74cfd30e55c5b7b8a531cc0b2c264871",
"md5": "8355ad9e7c9d948cf154570f2389c341",
"sha256": "29b15932ad72db487d66ea6cef7f411a94d445cfa04fcd17ed11f39c673e76b5"
},
"downloads": -1,
"filename": "streamlit_realtime_audio-0.0.7.tar.gz",
"has_sig": false,
"md5_digest": "8355ad9e7c9d948cf154570f2389c341",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 106049,
"upload_time": "2025-07-18T02:29:16",
"upload_time_iso_8601": "2025-07-18T02:29:16.101295Z",
"url": "https://files.pythonhosted.org/packages/83/d9/2829ca11e848288a153a9e5a923a74cfd30e55c5b7b8a531cc0b2c264871/streamlit_realtime_audio-0.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 02:29:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bronsonhill",
"github_project": "streamlit-realtime-audio",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "streamlit",
"specs": [
[
">=",
"1.28.0"
]
]
},
{
"name": "streamlit-realtime-audio",
"specs": [
[
"==",
"0.0.6"
]
]
}
],
"lcname": "streamlit-realtime-audio"
}