Spelling Bee Practice Workflow

This folder contains:

• generate_audio.py — reads a 2-column CSV and generates MP3 files using ElevenLabs.
• index.html — local interactive practice page.
• sample_words.csv — example CSV input.

1) Install Python dependency

python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install requests export ELEVENLABS_API_KEY="" python generate_audio.py sample_words.csv --voice-id BHf91PCMVcVwq6r1ku7L --output-dir ./audio

pip install requests

2) Set your ElevenLabs API key

macOS / Linux

export ELEVENLABS_API_KEY="YOUR_API_KEY"

Windows PowerShell

$env:ELEVENLABS_API_KEY="YOUR_API_KEY"

3) Choose a voice ID

Use a voice ID from your ElevenLabs account. BHf91PCMVcVwq6r1ku7L

4) Generate MP3 files

python generate_audio.py sample_words.csv --voice-id YOUR_VOICE_ID --output-dir ./audio

That command also generates audio/manifest.json.

By default, generate_audio.py now sends these ElevenLabs settings:

• model_id: eleven_multilingual_v2
• language_code: en
• output_format: mp3_44100_128
• speed: 0.85
• stability: 0.80
• similarity_boost: 1.00
• style: 0.00
• use_speaker_boost: false

You can override any of them with CLI flags such as --speed, --stability, --similarity-boost, --style, --speaker-boost, or --no-speaker-boost.

5) Open the page

Double-click index.html.

CSV rules

The CSV uses only these two columns:

1. filename
2. text

No other columns are needed.

Recommended filename pattern:

• Word_<word>
• Definition_<word>
• Sentence_<word>

Examples:

• Word_abacus
• Definition_abacus
• Sentence_abacus

Notes about the local HTML page

Browsers do not safely enumerate arbitrary local folders from a plain HTML file. Because of that, the page reads audio/manifest.json, which is generated by generate_audio.py.

Regenerating the manifest without calling ElevenLabs again

python generate_audio.py ignored.csv --voice-id ANYTHING --output-dir ./audio --manifest-only

The csv_path argument is ignored when --manifest-only is used.

If your MP3 files already exist

Run:

python generate_audio.py dummy.csv --voice-id ignored --output-dir ./audio --manifest-only

The CSV and voice are ignored in --manifest-only mode. This only scans the audio folder and rebuilds:

• audio/manifest.json
• audio/manifest.js

Then double-click index.html.

Expected audio names

• Word_abacus.mp3
• Definition_abacus.mp3
• Sentence_abacus.mp3

The shared suffix (abacus) is what groups the three files into one card.