README.md

---
title: Word Counter
emoji: 🎤
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.10.0
app_file: app.py
pinned: false
---

# Word Counter

A real-time speech recognition app that counts occurrences of a user-specified word from microphone input.

## How to Use

1. Enter the word you want to count in the **Target Word** field
2. Click the microphone button to start recording
3. Speak naturally - the app will transcribe your speech in real-time
4. Watch the counter increment each time it detects your target word
5. Click **Reset** to clear the counter and start over

## Features

- 🎤 Real-time speech recognition using OpenAI Whisper
- 🔢 Live counter updates
- 🎯 Case-insensitive word matching with proper word boundaries
- 🔄 Reset functionality
- 💻 Runs on CPU (no GPU required)

## Technical Details

- **Speech Recognition**: Whisper Tiny model for fast CPU inference
- **Framework**: Gradio for the user interface
- **Word Detection**: Regex-based matching with word boundaries to avoid false positives

## Architecture

The app is built with separation of concerns:
- `counter/` - Counter state management and word detection logic
- `model/` - Speech recognition wrapper
- `ui/` - Gradio interface components (now integrated in app.py)
- `app.py` - Main application with all components wired together

## Local Development

### Prerequisites

Install ffmpeg (required for audio processing):

**macOS:**
```bash
brew install ffmpeg
```

**Ubuntu/Debian:**
```bash
sudo apt-get install ffmpeg
```

**Windows:**
```bash
# Using chocolatey
choco install ffmpeg

# Or download from https://ffmpeg.org/download.html
```

### Setup

```bash
# Install dependencies with uv
uv sync

# (Optional) Configure Hugging Face token for faster downloads
# Copy .env.example to .env and add your token
cp .env.example .env
# Edit .env and add your HF token: HF_TOKEN="your_token_here"

# Run the app
uv run python app.py
```

**Note:** The HF_TOKEN is optional but recommended to avoid rate limits and warnings when downloading models from Hugging Face Hub. Get your token at https://huggingface.co/settings/tokens

## Testing

```bash
# Test counter logic
uv run python test_counter.py

# Test speech recognition
uv run python test_speech.py [optional-audio-file.wav]

# Test UI
uv run python test_ui.py
```