Audio-to-Text CLI

A real-time audio transcription application using Amazon Transcribe with speaker diarization support. Captures audio from system sources and provides live transcription with automatic speaker identification.

Features

• Real-time transcription using Amazon Transcribe Streaming API
• Speaker diarization with automatic speaker change detection
• Multi-source audio input discovery and selection
• System audio capture support via BlackHole integration
• Automatic retry with AWS-recommended resilience patterns
• Clean output formatting with speaker labels and timestamps

Documentation

For detailed technical information, see the docs/ directory:

📋 Implementation Guides

• Transcribe Integration Analysis - Complete AWS Transcribe streaming analysis
• Implementation Design - Architecture and design decisions
• Interface Design - Core interfaces and abstractions
• Java Audio Summary - Java Sound API deep dive

📚 Reference Materials

• AWS Transcribe Documentation - Official AWS docs and code samples
  • Streaming API
  • Setup Guide
  • Partial Results
  • Code Samples - Official AWS examples
• Java Audio API - Oracle Java Sound documentation
  • Audio Capturing
  • Audio Playing
  • Device Access

Prerequisites

System Requirements

• Java 11+ (tested with Java 11-21)
• macOS (primary support)
• AWS Account with Transcribe permissions

AWS Configuration

Configure AWS credentials using one of:

# AWS CLI
aws configure

# Environment variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-east-1

BlackHole Setup (Required for System Audio)

To capture system audio (music, videos, calls), install BlackHole:

# Install via Homebrew
brew install blackhole-2ch

Configure Audio Routing:

1. Open Audio MIDI Setup (Applications → Utilities)
2. Create Multi-Output Device:
   • Click "+" → Create Multi-Output Device
   • Check both "BlackHole 2ch" and your speakers/headphones
   • Set as system output device
3. Run the application and select "BlackHole 2ch" as input source

This setup allows you to:

• Hear audio through your speakers/headphones
• Capture system audio for transcription
• Transcribe music, videos, calls, or any system audio

Building the Project

Build JAR

./gradlew build

Create Standalone JAR

./gradlew standaloneJar

The standalone JAR will be created at:

build/libs/AudioToTextApplication-standalone.jar

Running the Application

From Source

./gradlew run

Standalone JAR

java -jar build/libs/AudioToTextApplication-standalone.jar

Usage Flow

1. Start the application
2. Select audio input sources from the discovered list
   • Enter comma-separated numbers (e.g., 1,3 for multiple sources)
   • Choose "BlackHole 2ch" for system audio
   • Choose microphone for voice input
3. Configure output destination:
   • Console output: Real-time display in terminal
   • File output: Save to files with options for:
     • Single file for all sources or separate files per source
     • Append to existing files or overwrite
4. Begin speaking or play audio
5. View real-time transcription with speaker labels
6. Press Ctrl+C to stop

Sample Output

==============================
Available Audio Input Sources:
==============================
1. Built-in Microphone - Built-in Microphone (Microphone Input)
2. BlackHole 2ch - BlackHole 2ch (System Audio Loopback)
==============================

Select input sources (comma-separated numbers, e.g., 1,3,5): 2

Output destination:
1. Console (real-time display)
2. File (save to disk)
Select option (1-2): 1

Starting transcription for 1 source(s)...
Press Ctrl+C to stop transcription.
Started transcription for: BlackHole 2ch

[Built-in Microphone]: Speaker 1: "Good morning everyone, thanks for joining today's standup meeting"
[BlackHole 2ch]: Speaker 2: "Morning! I can see we have a few agenda items to cover"
[Built-in Microphone]: Speaker 3: "Let's start with project updates and then move to blockers"
[BlackHole 2ch]: Speaker 4: "I'll go first - completed the API integration yesterday"
[BlackHole 2ch]: Speaker 5: "Great work! I'm still working on the frontend components"
[BlackHole 2ch]: Speaker 2: "Any blockers we should discuss?"

Architecture

• AudioInputDiscovery: Discovers and filters available audio input devices
• TranscribeService: Manages AWS Transcribe streaming with retry logic
• AudioStreamPublisher: Reactive streams publisher for audio data
• TranscriptionResultHandler: Processes results with speaker diarization
• Automatic Retry: Handles timeouts and network issues gracefully

Troubleshooting

No Audio Captured

• Ensure BlackHole is installed and configured
• Check system audio output is set to Multi-Output Device
• Verify AWS credentials are configured

Transcription Errors

• Check AWS region configuration
• Verify internet connectivity
• Ensure AWS Transcribe permissions

Build Issues

• Ensure Java 11+ is installed
• Run ./gradlew clean build for clean rebuild

Dependencies

• AWS SDK for Java - Transcribe Streaming API
• Lombok - Code generation
• SLF4J + Logback - Logging
• BlackHole - Virtual audio driver (external)

License

This project is for educational and development purposes.