README.md

metadata

title: ShadowLoop
emoji: 🔁
colorFrom: gray
colorTo: green
sdk: gradio
sdk_version: 6.13.0
app_file: app.py
python_version: '3.11'
pinned: false

ShadowLoop

Local sentence-level repetition trainer for English shadowing practice. Upload audio, review sentence segments, configure repeats and pauses, download a practice MP3.

Requirements

• Python 3.11+
• ffmpeg (sudo apt install ffmpeg or brew install ffmpeg)

Install

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

First run will download the Whisper base model (~140 MB).

Usage

source .venv/bin/activate
python app.py

Open the URL shown in the terminal (typically http://0.0.0.0:7860).

Workflow

1. Upload an audio file and click Transcribe (or upload a .txt transcript instead)
2. Review the detected sentences — merge, split, or delete as needed
3. Configure repeat count, pauses, and playback speed
4. Click Build Practice Audio, preview, and download the MP3

Settings

Setting	Default	Range
Repeat count	8	1–20
Pause between repeats	2.5s	0–10s
Pause between sentences	4s	1–15s
Playback speed	1.0x	0.5x–2.0x

Speed is applied to the exported MP3 (pitch-preserving via ffmpeg atempo).

Tests

python -m pytest

Project Structure

app.py                        # Gradio UI
src/shadowloop/
    config.py                 # Segment + ShadowingConfig dataclasses
    ingest.py                 # Audio loading and normalization
    segmenter.py              # Whisper transcription + sentence splitting + edit ops
    planner.py                # Repeat/pause plan generation
    builder.py                # Audio assembly with speed change
    exporters.py              # MP3 export
tests/
    test_config.py
    test_segmenter.py
    test_planner.py
    test_builder.py