This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

Voice Accessibility CLI - An open-source Python command-line tool and API that turns short text descriptions into MP3 speech through the ElevenLabs cloud text-to-speech service.

The project explores a practical accessibility use case: making a written alert available as a spoken audio file. It can support:

• People who benefit from audio alerts, including people with visual impairments
• Busy homeowners who want to listen to an alert while away from a screen
• Smart-home developers who want to connect their own event workflow to text-to-speech
• Community contributors who want to build accessible notification tools on an open-source foundation

The CLI accepts text or a simple event description and saves the returned audio as an MP3. It does not connect directly to Ring, Wyze, or other smart-home platforms, play audio through speakers, or replace the surrounding automation that captures and delivers an event.

Demo

Live Repository: github.com/abdelrazekrizk/voice-accessibility-cli

The tool needs Python dependencies, an ElevenLabs API key, and network access for real audio generation. Follow the repository setup guide first. From the project root in PowerShell:

Quick Start:

# Generate an MP3 from text
& .\.venv\Scripts\python.exe src\cli.py generate --text "Motion detected at the back gate" --output alert.mp3

# Compose an event alert from type, location, and urgency
& .\.venv\Scripts\python.exe src\cli.py event --event-type motion --location "Backyard" --urgency high --output motion-alert.mp3

# Process JSON text strings from a list or an object with a "texts" list
& .\.venv\Scripts\python.exe src\cli.py batch --input-file .\texts.json --output-dir .\audio_output\alerts

# Show the built-in voice-name list
& .\.venv\Scripts\python.exe src\cli.py list-voices

Relative output paths are saved under audio_output/. The list-voices command currently shows a built-in list; it does not query the voices enabled for an account.

Sample Output:

• Input: Motion detected at the back gate
• Output: An MP3 file such as audio_output/alert.mp3; the CLI reports its path, file size, and estimated duration.
• Use case: An application can play or forward the generated file as part of its own notification workflow.

Real requests send text to ElevenLabs and may consume account quota or incur charges. The automated tests mock the SDK and do not make external requests.

Code

abdelrazekrizk / voice-accessibility-cli

Voice Accessibility CLI

A Python command-line tool and API that turns short text or smart-home event descriptions into MP3 speech using the ElevenLabs cloud text-to-speech service. Audio is generated remotely; this project does not include an offline speech model.

• Repository: github.com/abdelrazekrizk/voice-accessibility-cli
• License: MIT

What it does

Use the generate command to submit text to ElevenLabs, event to compose a spoken event alert, or batch to generate files for a list of text strings. The Python API returns audio bytes and metadata, and can optionally save the audio under audio_output/.

An ElevenLabs API key and network access are required for real generation. API usage may incur charges or be subject to account and voice restrictions. Unit tests mock the SDK and do not make requests.

Backboard belongs to the optional event-comparison helper in the sibling Event Schema Validator project; it is not required by this CLI. The included event-validator…

View on GitHub

Architecture:

• src/audio.py: AccessibleAudio sends text to ElevenLabs, collects audio bytes, optionally saves MP3 files, and returns metadata. EventToSpeech formats a basic event description before generation.
• src/cli.py: Click commands for generate, event, batch, list-voices, and version.
• tests/test_audio.py: Tests configuration, metadata, output handling, and audio generation using mocked ElevenLabs calls.
• examples/event_validator_audio_demo.py: Optional example that uses the sibling event validator locally, then sends narration text to ElevenLabs.

Key Features:

• ✅ Generate MP3 speech from supplied text using the ElevenLabs SDK
• ✅ Compose a short alert from event type, location, and urgency
• ✅ Process a JSON array of text strings or an object with a texts array
• ✅ Return audio bytes and metadata; optionally save output under audio_output/
• ✅ Retry with configured fallback voice/model only for the handled HTTP 402 paid_plan_required case
• ✅ Mocked tests that run without credentials or live API calls
• ⚠️ The CLI accepts --voice, --rate, --stability, and --similarity, but those values are not currently passed to the SDK as synthesis settings. To choose a provider voice ID, use AudioConfig.voice_id through the Python API.

How I Built It

Core Technology Stack:

• ElevenLabs SDK - Cloud text-to-speech; account access and pricing depend on the provider's current terms
• Python 3.10+ - Application and CLI implementation
• Pydantic - Audio configuration and metadata models
• Click - Command-line interface
• pytest - Automated tests with mocked SDK calls

Integration Highlights:

1. Text-to-Speech API: Sends supplied text to ElevenLabs and collects the returned MP3 data.
2. Event-to-Speech Helper: Builds a short narration from event type, location, and urgency; it does not parse vendor event schemas.
3. Optional File Output: Saves generated audio to the requested path and returns file metadata.
4. Targeted Fallback: Retries with configured fallback IDs for the specific paid-plan restriction handled by the implementation.
5. Offline Testability: Tests mock remote SDK calls, so routine test runs need no API key and do not generate real audio.

Development Approach:

• Keep the CLI and Python API small and easy to integrate into another application.
• Use the ElevenLabs service for synthesis rather than downloading a local speech model.
• Make network use explicit: real text-to-speech requests transmit text to a third-party service.
• Document implementation limits so callers do not mistake stored configuration options for working synthesis controls.

Why Does Open Innovation Matter?

This project demonstrates several benefits of an open implementation:

1. Accessibility & Adaptation

• Developers can inspect and adapt how text is converted into an audio artifact.
• The Python API can be incorporated into a larger notification workflow.
• People can propose improvements and integrations without building a CLI from scratch.

2. Transparency & Data Handling

• The repository makes the request flow and current limitations inspectable.
• The source code is open, but real audio generation is performed by ElevenLabs; text is sent to that provider and is subject to its terms and account settings.
• Callers should avoid sending sensitive event details unless they are permitted to share them.

3. Customization & Extensibility

• The AccessibleAudio and EventToSpeech APIs provide starting points for applications with their own event sources.
• The project does not include vendor-specific event validators; integrations can transform their events into short text before calling this API.
• Contributors can improve supported provider settings and add tests as the implementation evolves.

4. Reduces Screen Dependency

• A generated audio file can be used in a workflow where listening is more convenient than reading a notification.
• Playback and delivery are left to the calling application or user; this CLI generates and optionally saves the audio file.

5. Community & Contribution

• Built with familiar open-source tools: Python, Click, Pydantic, and pytest.
• MIT licensed for reuse and modification.
• Tests use mocks, making the core test suite accessible without API credentials.

Prize Categories

• Best Use of ElevenLabs - The project uses the ElevenLabs SDK for cloud text-to-speech.
• Touch Grass Theme - The use case is voice-based access to text alerts, with audio delivery/playback supplied by the surrounding workflow.

---

Developed by: @abdelrazekrizk
Repository: github.com/abdelrazekrizk/voice-accessibility-cli
License: MIT - Open for community contributions

Tags: #devchallenge #hf26challenge #ElevenLabs #OpenSourceAI #Accessibility #SmartHome #VoiceAI