Transcriptions

An Elixir application for transcribing audio files using OpenAI's Whisper API. This tool automatically scans directories for audio files and generates markdown transcriptions, while avoiding duplicate work by checking for existing transcription files.

Features

• 🎵 Multiple Audio Formats: Supports MP3, WAV, M4A, MP4, WebM, and FLAC files
• 🤖 OpenAI Whisper Integration: Uses OpenAI's powerful Whisper API for accurate transcription
• 📝 Markdown Output: Generates clean markdown files with metadata and transcriptions
• 🔄 Duplicate Prevention: Automatically skips files that already have corresponding markdown files
• 📊 Progress Tracking: Shows real-time progress and summary statistics
• ⚡ Mix Task Interface: Simple command-line interface via Mix tasks

Prerequisites

• Elixir 1.17 or higher
• OpenAI API key (set as OPENAI_API_KEY environment variable)

Installation

1. Clone this repository:

git clone <repository-url>
cd transcriptions

2. Install dependencies:

mix deps.get

3. Set your OpenAI API key:

export OPENAI_API_KEY="your-api-key-here"

Usage

Basic Usage

Place your audio files in the transcriptions/ directory and run:

mix transcribe

This will:

1. Scan the transcriptions/ directory for supported audio files
2. Skip any files that already have corresponding .md files
3. Transcribe remaining files using OpenAI's Whisper API
4. Save transcriptions as markdown files with the same base name

Advanced Options

# Specify a custom directory
mix transcribe --directory /path/to/audio/files

# Use a specific Whisper model
mix transcribe --model whisper-1

# Specify the audio language (for better accuracy)
mix transcribe --language en

# Combine options
mix transcribe --directory ./recordings --language es --model whisper-1

Available Options

• --directory (-d): Directory to scan for audio files (default: "transcriptions")
• --model (-m): OpenAI Whisper model to use (default: "whisper-1")
• --language (-l): Language code for the audio (optional, auto-detected if not provided)
• --help (-h): Show help information

Supported Audio Formats

• MP3 (.mp3)
• WAV (.wav)
• M4A (.m4a)
• MP4 (.mp4)
• WebM (.webm)
• FLAC (.flac)

Example Output

For an audio file meeting.mp3, the tool generates meeting.md:

# Transcription: meeting.mp3

## Metadata

- **File**: meeting.mp3
- **Size**: 2.5 MB
- **Modified**: 2023-12-01T14:30:00Z
- **Transcribed**: 2023-12-01T15:45:00Z
- **Model**: OpenAI Whisper

## Transcription

Welcome to today's team meeting. We'll be discussing the quarterly results and planning for next quarter...

Development

Running Tests

# Run all tests
mix test

# Run specific test files
mix test test/transcriptions/service_test.exs

# Run tests with coverage
mix test --cover

Integration Tests

Integration tests that make actual API calls are tagged with :integration and require a valid OpenAI API key:

mix test --include integration

Project Structure

lib/
├── transcriptions.ex                 # Main application module
├── transcriptions/
│   ├── application.ex               # Application supervision tree
│   ├── file_scanner.ex             # Audio file discovery utilities
│   ├── openai_client.ex            # OpenAI API client
│   └── service.ex                  # Main transcription service
└── mix/
    └── tasks/
        └── transcribe.ex            # Mix task implementation

test/
├── transcriptions/                  # Unit tests for modules
├── mix/tasks/                      # Mix task tests
└── support/fixtures/               # Test fixtures and utilities

Configuration

The application uses environment variables for configuration:

• OPENAI_API_KEY (required): Your OpenAI API key

Error Handling

The application handles various error scenarios gracefully:

• Missing API Key: Clear error message with instructions
• Invalid API Key: Displays OpenAI error response
• Quota Exceeded: Shows quota error from OpenAI
• File Access Errors: Reports file permission or not-found errors
• Network Issues: Handles HTTP request failures

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.