Turn three basic facts about a local business into a broadcast-ready 30-second commercial audio ad using Google Gemma open weights, deterministic text normalization, ElevenLabs studio voice synthesis, and FFmpeg audio mixing.
-orange.svg){kind=icon}
🚀 Live Deployed App: https://spotforge.onrender.com (Hosted on Render free tier; if idle, initial spin-up takes ~50s)
đź“– Official Hacktoberfest Submission: Read on DEV Community
Neighborhood businesses—pizzerias, barbershops, auto mechanics, dental practices—frequently need high-impact promotional audio for social video (Instagram Stories, TikTok Ads), local radio, or telephone hold messaging.
Most cannot afford traditional production:
- Creative Agencies and Studios: Cost $300 to $800 per 30-second spot for scriptwriting, studio recording, and voice talent.
- Manual Recording: Cellphone microphone recordings lack commercial energy, proper breathing pauses, and background music, leading listeners to scroll away.
SpotForge converts 3 business inputs (business name, core offer, and call to action) into an air-ready commercial ad in seconds:
- AIDA Ad Copywriting: Google Gemma 4 generates a structured script (Attention -> Interest -> Desire -> Action) constrained by speech cadence targets (~2.5 words/second in Spanish, ~2.8 words/second in English).
- Phonetic Normalization: A deterministic rule engine converts promotions (
2x1), currencies ($15), percentages (30%), and phone numbers (555-0199) into natural spoken words with breathing pauses. - Studio Voice Synthesis: ElevenLabs renders the normalized text with commercial inflection and crisp diction.
- Physical Duration Audit: Measures actual runtime from the MP3 header with
mutagen. If the take exceeds target length by over 3 seconds, it triggers a single adaptive retry with a proportionally reduced word budget. - Background Music Mixing: FFmpeg loops and blends a royalty-free CC0 musical bed with 15% volume ducking under the voice and a 2-second tail fadeout.
Three sample spots produced end-to-end with the pipeline (Gemma 4 + Phonetic Normalizer + ElevenLabs + FFmpeg):
| Business | Category | Voice Talent | Music Bed | Real Duration | Audio File |
|---|---|---|---|---|---|
| PizzerĂa Don Mario | Wood-fired artisanal Italian pizzeria | George | Upbeat Commercial (110 BPM) | 28.4s | demo_pizzeria.mp3 |
| BarberĂa El Bigote | Executive men's grooming & hot towel | Liam | Urban Energy (120 BPM) | 31.9s | demo_barber.mp3 |
| Apex Auto Repair | Multi-brand automotive mechanics & brakes | Roger | Chill Acoustic (75 BPM) | 27.3s | demo_autorepair.mp3 |
Many AI projects claim "$0 cost" by glossing over third-party licensing. Commercial resale of synthesized voiceover requires clear licensing:
| Parameter | ElevenLabs Starter Plan ($6/mo) | Traditional Audio Agency |
|---|---|---|
| Copywriting (Gemma 4) | $0.00 (Google AI Studio Free Tier or local Ollama) | $150 – $300 (Copywriter) |
| Voiceover (ElevenLabs) | $0.08 (within 30k char quota) / $0.12 extra | $150 – $500 (Studio + Talent) |
| Mixing & Music (FFmpeg) | $0.00 (Server-side process + CC0 Music Beds) | $50 – $100 (Sound engineer) |
| Total Production Cost | $0.08 – $0.12 USD | $350 – $900 USD |
| Suggested Resale Price | $5.00 – $15.00 USD | $350 – $900 USD |
| Gross Profit Margin | 97.6% – 99.2% | N/A |
| Ads Included in $6/mo | ~75 commercial ads of 30 seconds | 0 |
Freelance Economics: Managing social media for 5 local clients with 2 fresh promo spots per week produces $150/month in revenue against $6 in software costs—a defensible, high-margin side hustle.
- Open Weights for Core Copywriting: Built on Google Gemma 4 (
gemma-4-26b-a4b-it). Open-weight models protect developers from closed API price spikes and deprecations. - Offline and Cloud Portability: Implements
BaseLLMBackend. The system runs via Google AI Studio in the cloud or 100% offline using local Ollama (LLM_BACKEND=ollama), keeping unreleased client promotions and private numbers on-premises. - Open Standards: Relies on FFmpeg for audio processing and public domain CC0 music beds.
flowchart TD
A["Business Input\n(Name, Offer, CTA, Tone)"] --> B["Gemma 4 Copywriter\n(Single-prompt AIDA)"]
B --> C["Phonetic Normalizer\n(2x1 -> two for one, $15 -> fifteen dollars)"]
C --> D["ElevenLabs Voice\n(Multilingual v2 - Roger, George, Sarah, Liam)"]
D --> E["Duration Measurement\n(Mutagen binary MP3 audit)"]
E -- "Exceeds target + 3s?" --> F["Adaptive 1-Retry Loop\n(Proportional word-budget reduction)"]
F -.-> C
E -- "Within bounds" --> G["FFmpeg Audio Mixer\n(CC0 Bed + 15% Ducking + 2s Fadeout)"]
G --> H["Broadcast MP3 Output\n(static/audio/spot_uuid.mp3)"]
SpotForge is open-source software licensed under the MIT License.
Google Gemma is an open-weight model family distributed under the Gemma Terms of Use, permitting commercial use subject to Google's acceptable use policy.
- The Free Plan from ElevenLabs does not include commercial rights over generated audio. Free-tier audio may only be used for personal testing and requires public attribution.
- To resell audio spots to clients or run them in paid advertising (Instagram, TikTok, YouTube, radio, podcasts), users must hold at least the Starter Plan ($6 USD/month) with their own API key.
- SpotForge uses a Bring Your Own Key (BYOK) model: each user configures their own key in
.env. Commercial rights remain directly anchored to the user's active ElevenLabs tier.
All bundled background tracks are licensed under Creative Commons Zero (CC0 1.0 Universal / Public Domain). Full attributions and source metadata are tracked in static/music/LICENSES.md.
- Network Dependency for Voiceover: Speech synthesis requires outbound HTTPS connectivity to ElevenLabs. While the copywriting engine can run 100% offline via Ollama, audio synthesis depends on API connectivity.
- Cadence Variance Across Voice Profiles: Voice talents read at slightly different rates. SpotForge mitigates this through target word budgeting and an adaptive 1-retry loop, but edge cases may still require manual script tweaks in the UI.
- FFmpeg Binary Requirement: Background music mixing requires
ffmpegin systemPATH. If unavailable, SpotForge gracefully degrades to clean voiceover with an explicit, non-blocking warning. - Cloud LLM Rate Limits: Free-tier Google AI Studio accounts have standard RPM limits. High-concurrency production deployments should point
LLM_BACKEND=ollamato a local or self-hosted GPU instance.
Architectural decisions are formally recorded in docs/adr/:
- ADR-001: Adoption of Google Gemma 4 as Open-Weight Ad Copywriter
- ADR-002: High-Fidelity Studio Voice Synthesis with ElevenLabs
- ADR-003: FastAPI Backend and Minimalist Vanilla SPA Frontend
- ADR-004: Deterministic Phonetic Text Normalization Layer for TTS
- ADR-005: Commercial Licensing Integrity and BYOK Architecture
- ADR-006: Professional Background Musical Bed Mixing with FFmpeg
- ADR-007: Real MP3 Duration Measurement and Adaptive 1-Retry Pacing Loop
- Python 3.10+
- FFmpeg 6+ in system
PATH - Google AI Studio API Key (aistudio.google.com)
- ElevenLabs API Key (elevenlabs.io)
git clone https://github.com/oscarbol09/spotforge.git
cd spotforgepython -m venv venv
# On Windows:
venv\Scripts\activate
# On Linux / macOS:
source venv/bin/activate
pip install -r requirements.txtcp .env.example .envEdit .env:
GEMINI_API_KEY=your_gemini_api_key
ELEVENLABS_API_KEY=your_elevenlabs_api_key
GEMMA_MODEL_ID=gemma-4-26b-a4b-it
ELEVENLABS_MODEL=eleven_multilingual_v2
LLM_BACKEND=gemini # or 'ollama' for offline local inference
ENABLE_MUSIC_MIXING=true
AUDIO_TTL_HOURS=24docker build -t spotforge .
docker run -p 8000:8000 --env-file .env spotforgeuvicorn main:app --reload --port 8000Open http://localhost:8000 in your browser.
pytest -vAll 35 tests covering copy generation, duration control, text normalization, voice synthesis, storage TTL lifecycle, rate limiting, and asset serving should pass.
- Overall Winner ($250 USD): Full-featured project built for the Side Hustle prompt with transparent unit economics and freelance viability.
- Best Use of Gemma ($200 USD): AIDA prompt design on Google's open-weight Gemma 4 (
gemma-4-26b-a4b-it), thought token filtering, and local Ollama support. - Best Use of ElevenLabs ($100 USD): Commercial voice synthesis using ElevenLabs Multilingual v2, dynamic voice discovery, and exact character telemetry.
- Best Use of Render ($200 USD): Turnkey deployment blueprint in
render.yamlwith automated health checks.
Released under the MIT License. See LICENSE for details.