initial commit

17 files changed, 2232 insertions, 0 deletions

diff --git a/internal/anki/doc.go b/internal/anki/doc.go
new file mode 100644
index 0000000..5fd3d5f
--- /dev/null
+++ b/internal/anki/doc.go
@@ -0,0 +1,3 @@
+// Package anki provides functionality to generate Anki-compatible
+// flashcard formats from Bulgarian words, audio, and images.
+package anki
\ No newline at end of file
diff --git a/internal/anki/generator.go b/internal/anki/generator.go
new file mode 100644
index 0000000..22221f3
--- /dev/null
+++ b/internal/anki/generator.go
@@ -0,0 +1,318 @@
+package anki
+
+import (
+	"encoding/csv"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// Card represents a single Anki flashcard
+type Card struct {
+	Bulgarian   string   // The Bulgarian word/phrase
+	AudioFile   string   // Path to audio file
+	ImageFiles  []string // Paths to image files
+	Translation string   // Optional translation
+	Notes       string   // Optional notes
+}
+
+// GeneratorOptions configures the Anki export
+type GeneratorOptions struct {
+	OutputPath      string // Output CSV file path
+	MediaFolder     string // Folder containing media files
+	IncludeHeaders  bool   // Include CSV headers
+	AudioFormat     string // Audio file format (mp3, wav)
+	ImageFormat     string // Image file format (jpg, png)
+}
+
+// DefaultGeneratorOptions returns sensible defaults
+func DefaultGeneratorOptions() *GeneratorOptions {
+	return &GeneratorOptions{
+		OutputPath:     "anki_import.csv",
+		MediaFolder:    ".",
+		IncludeHeaders: true,
+		AudioFormat:    "mp3",
+		ImageFormat:    "jpg",
+	}
+}
+
+// Generator creates Anki-compatible import files
+type Generator struct {
+	options *GeneratorOptions
+	cards   []Card
+}
+
+// NewGenerator creates a new Anki generator
+func NewGenerator(options *GeneratorOptions) *Generator {
+	if options == nil {
+		options = DefaultGeneratorOptions()
+	}
+	return &Generator{
+		options: options,
+		cards:   make([]Card, 0),
+	}
+}
+
+// AddCard adds a card to the collection
+func (g *Generator) AddCard(card Card) {
+	g.cards = append(g.cards, card)
+}
+
+// GenerateCSV creates a CSV file for Anki import
+func (g *Generator) GenerateCSV() error {
+	// Create output file
+	file, err := os.Create(g.options.OutputPath)
+	if err != nil {
+		return fmt.Errorf("failed to create CSV file: %w", err)
+	}
+	defer file.Close()
+	
+	// Create CSV writer
+	writer := csv.NewWriter(file)
+	defer writer.Flush()
+	
+	// Write headers if requested
+	if g.options.IncludeHeaders {
+		headers := []string{"Bulgarian", "Audio", "Image", "Translation", "Notes"}
+		if err := writer.Write(headers); err != nil {
+			return fmt.Errorf("failed to write headers: %w", err)
+		}
+	}
+	
+	// Write cards
+	for _, card := range g.cards {
+		record := []string{
+			card.Bulgarian,
+			g.formatAudioField(card.AudioFile),
+			g.formatImageField(card.ImageFiles),
+			card.Translation,
+			card.Notes,
+		}
+		
+		if err := writer.Write(record); err != nil {
+			return fmt.Errorf("failed to write card: %w", err)
+		}
+	}
+	
+	return nil
+}
+
+// formatAudioField formats the audio file reference for Anki
+func (g *Generator) formatAudioField(audioFile string) string {
+	if audioFile == "" {
+		return ""
+	}
+	
+	// Get just the filename
+	filename := filepath.Base(audioFile)
+	
+	// Anki audio format: [sound:filename.mp3]
+	return fmt.Sprintf("[sound:%s]", filename)
+}
+
+// formatImageField formats image file references for Anki
+func (g *Generator) formatImageField(imageFiles []string) string {
+	if len(imageFiles) == 0 {
+		return ""
+	}
+	
+	// For multiple images, we'll use HTML to display them
+	if len(imageFiles) == 1 {
+		filename := filepath.Base(imageFiles[0])
+		return fmt.Sprintf(`<img src="%s">`, filename)
+	}
+	
+	// Multiple images - create a simple layout
+	var html strings.Builder
+	html.WriteString(`<div style="display: flex; flex-wrap: wrap; gap: 10px;">`)
+	
+	for _, imageFile := range imageFiles {
+		filename := filepath.Base(imageFile)
+		html.WriteString(fmt.Sprintf(`<img src="%s" style="max-width: 200px; height: auto;">`, filename))
+	}
+	
+	html.WriteString(`</div>`)
+	return html.String()
+}
+
+// GenerateFromDirectory creates cards from a directory of materials
+func (g *Generator) GenerateFromDirectory(dir string) error {
+	// Map to group files by word
+	wordFiles := make(map[string]*Card)
+	
+	// Walk the directory
+	err := filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		
+		// Skip directories
+		if info.IsDir() {
+			return nil
+		}
+		
+		// Get filename without extension
+		filename := info.Name()
+		ext := filepath.Ext(filename)
+		base := strings.TrimSuffix(filename, ext)
+		
+		// Skip attribution files
+		if strings.HasSuffix(base, "_attribution") {
+			return nil
+		}
+		
+		// Extract word from filename (assumes format: word_type.ext or word_index.ext)
+		parts := strings.Split(base, "_")
+		if len(parts) == 0 {
+			return nil
+		}
+		
+		word := parts[0]
+		
+		// Get or create card for this word
+		card, exists := wordFiles[word]
+		if !exists {
+			card = &Card{
+				Bulgarian:  word,
+				ImageFiles: make([]string, 0),
+			}
+			wordFiles[word] = card
+		}
+		
+		// Add file to appropriate field
+		switch strings.ToLower(ext) {
+		case ".mp3", ".wav":
+			if card.AudioFile == "" { // Use first audio file found
+				card.AudioFile = path
+			}
+		case ".jpg", ".jpeg", ".png", ".gif":
+			card.ImageFiles = append(card.ImageFiles, path)
+		}
+		
+		return nil
+	})
+	
+	if err != nil {
+		return fmt.Errorf("failed to walk directory: %w", err)
+	}
+	
+	// Add all cards to generator
+	for _, card := range wordFiles {
+		g.AddCard(*card)
+	}
+	
+	return nil
+}
+
+// GeneratePackage creates a complete Anki package with media files
+func (g *Generator) GeneratePackage(outputDir string) error {
+	// Create output directory
+	if err := os.MkdirAll(outputDir, 0755); err != nil {
+		return fmt.Errorf("failed to create output directory: %w", err)
+	}
+	
+	// Create media directory
+	mediaDir := filepath.Join(outputDir, "collection.media")
+	if err := os.MkdirAll(mediaDir, 0755); err != nil {
+		return fmt.Errorf("failed to create media directory: %w", err)
+	}
+	
+	// Copy media files and update paths
+	for i, card := range g.cards {
+		// Copy audio file
+		if card.AudioFile != "" {
+			newPath, err := g.copyMediaFile(card.AudioFile, mediaDir)
+			if err != nil {
+				return fmt.Errorf("failed to copy audio file: %w", err)
+			}
+			g.cards[i].AudioFile = newPath
+		}
+		
+		// Copy image files
+		newImagePaths := make([]string, 0, len(card.ImageFiles))
+		for _, imagePath := range card.ImageFiles {
+			newPath, err := g.copyMediaFile(imagePath, mediaDir)
+			if err != nil {
+				return fmt.Errorf("failed to copy image file: %w", err)
+			}
+			newImagePaths = append(newImagePaths, newPath)
+		}
+		g.cards[i].ImageFiles = newImagePaths
+	}
+	
+	// Update output path to package directory
+	g.options.OutputPath = filepath.Join(outputDir, "import.csv")
+	
+	// Generate CSV
+	return g.GenerateCSV()
+}
+
+// copyMediaFile copies a media file to the destination directory
+func (g *Generator) copyMediaFile(src, destDir string) (string, error) {
+	// Get source file info
+	srcInfo, err := os.Stat(src)
+	if err != nil {
+		return "", err
+	}
+	
+	// Create destination path
+	filename := filepath.Base(src)
+	destPath := filepath.Join(destDir, filename)
+	
+	// Check if file already exists
+	if _, err := os.Stat(destPath); err == nil {
+		// File exists, generate unique name
+		ext := filepath.Ext(filename)
+		base := strings.TrimSuffix(filename, ext)
+		for i := 1; ; i++ {
+			filename = fmt.Sprintf("%s_%d%s", base, i, ext)
+			destPath = filepath.Join(destDir, filename)
+			if _, err := os.Stat(destPath); os.IsNotExist(err) {
+				break
+			}
+		}
+	}
+	
+	// Open source file
+	srcFile, err := os.Open(src)
+	if err != nil {
+		return "", err
+	}
+	defer srcFile.Close()
+	
+	// Create destination file
+	destFile, err := os.Create(destPath)
+	if err != nil {
+		return "", err
+	}
+	defer destFile.Close()
+	
+	// Copy content
+	if _, err := destFile.ReadFrom(srcFile); err != nil {
+		return "", err
+	}
+	
+	// Preserve file mode
+	if err := os.Chmod(destPath, srcInfo.Mode()); err != nil {
+		return "", err
+	}
+	
+	return filename, nil
+}
+
+// Stats returns statistics about the card collection
+func (g *Generator) Stats() (totalCards, withAudio, withImages int) {
+	totalCards = len(g.cards)
+	
+	for _, card := range g.cards {
+		if card.AudioFile != "" {
+			withAudio++
+		}
+		if len(card.ImageFiles) > 0 {
+			withImages++
+		}
+	}
+	
+	return
+}
\ No newline at end of file
diff --git a/internal/audio/doc.go b/internal/audio/doc.go
new file mode 100644
index 0000000..1fd216b
--- /dev/null
+++ b/internal/audio/doc.go
@@ -0,0 +1,3 @@
+// Package audio provides audio generation functionality using espeak-ng
+// for Bulgarian text-to-speech conversion.
+package audio
diff --git a/internal/audio/espeak.go b/internal/audio/espeak.go
new file mode 100644
index 0000000..cd42360
--- /dev/null
+++ b/internal/audio/espeak.go
@@ -0,0 +1,217 @@
+package audio
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+)
+
+// ESpeakConfig holds configuration for espeak-ng audio generation
+type ESpeakConfig struct {
+	Voice     string // Voice variant (e.g., "bg", "bg+m1", "bg+f1")
+	Speed     int    // Speech speed in words per minute (default: 150)
+	Pitch     int    // Pitch adjustment, 0 to 99 (default: 50)
+	Amplitude int    // Volume/amplitude, 0 to 200 (default: 100)
+	WordGap   int    // Gap between words in 10ms units (default: 0)
+	OutputDir string // Directory for output files
+}
+
+// DefaultConfig returns the default configuration for Bulgarian voice
+func DefaultConfig() *ESpeakConfig {
+	return &ESpeakConfig{
+		Voice:     "bg",
+		Speed:     150,
+		Pitch:     50,
+		Amplitude: 100,
+		WordGap:   0,
+		OutputDir: "./",
+	}
+}
+
+// ESpeak provides an interface to the espeak-ng text-to-speech engine
+type ESpeak struct {
+	config *ESpeakConfig
+}
+
+// New creates a new ESpeak instance with the given configuration
+func New(config *ESpeakConfig) (*ESpeak, error) {
+	// Check if espeak-ng is installed
+	if err := checkESpeakInstalled(); err != nil {
+		return nil, err
+	}
+	
+	if config == nil {
+		config = DefaultConfig()
+	}
+	
+	return &ESpeak{config: config}, nil
+}
+
+// GenerateAudio generates an audio file for the given Bulgarian text
+func (e *ESpeak) GenerateAudio(text string, outputFile string) error {
+	// Validate input
+	if text == "" {
+		return fmt.Errorf("text cannot be empty")
+	}
+	
+	// Ensure output directory exists
+	dir := filepath.Dir(outputFile)
+	if dir != "" && dir != "." {
+		if err := os.MkdirAll(dir, 0755); err != nil {
+			return fmt.Errorf("failed to create output directory: %w", err)
+		}
+	}
+	
+	// Build espeak-ng command
+	args := []string{
+		"-v", e.config.Voice,  // Voice selection
+		"-s", fmt.Sprintf("%d", e.config.Speed),  // Speed
+		"-p", fmt.Sprintf("%d", e.config.Pitch),  // Pitch
+		"-a", fmt.Sprintf("%d", e.config.Amplitude),  // Amplitude/volume
+	}
+	
+	// Add word gap if specified
+	if e.config.WordGap > 0 {
+		args = append(args, "-g", fmt.Sprintf("%d", e.config.WordGap))
+	}
+	
+	// Add output file and text
+	args = append(args, "-w", outputFile, text)
+	
+	cmd := exec.Command("espeak-ng", args...)
+	
+	// Run the command
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("espeak-ng failed: %w\nOutput: %s", err, string(output))
+	}
+	
+	return nil
+}
+
+// SetVoice updates the voice variant
+func (e *ESpeak) SetVoice(voice string) {
+	e.config.Voice = voice
+}
+
+// SetSpeed updates the speech speed
+func (e *ESpeak) SetSpeed(speed int) {
+	if speed < 80 {
+		speed = 80
+	} else if speed > 450 {
+		speed = 450
+	}
+	e.config.Speed = speed
+}
+
+// SetPitch updates the pitch (0-99, 50 is default)
+func (e *ESpeak) SetPitch(pitch int) {
+	if pitch < 0 {
+		pitch = 0
+	} else if pitch > 99 {
+		pitch = 99
+	}
+	e.config.Pitch = pitch
+}
+
+// SetAmplitude updates the volume/amplitude (0-200, 100 is default)
+func (e *ESpeak) SetAmplitude(amplitude int) {
+	if amplitude < 0 {
+		amplitude = 0
+	} else if amplitude > 200 {
+		amplitude = 200
+	}
+	e.config.Amplitude = amplitude
+}
+
+// SetWordGap updates the gap between words in 10ms units
+func (e *ESpeak) SetWordGap(gap int) {
+	if gap < 0 {
+		gap = 0
+	}
+	e.config.WordGap = gap
+}
+
+// checkESpeakInstalled verifies that espeak-ng is available on the system
+func checkESpeakInstalled() error {
+	cmd := exec.Command("espeak-ng", "--version")
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("espeak-ng is not installed or not in PATH: %w", err)
+	}
+	return nil
+}
+
+// ValidateBulgarianText performs basic validation of Bulgarian text
+func ValidateBulgarianText(text string) error {
+	if text == "" {
+		return fmt.Errorf("text cannot be empty")
+	}
+	
+	// Check if text contains at least one Cyrillic character
+	hasCyrillic := false
+	for _, r := range text {
+		// Bulgarian Cyrillic range
+		if (r >= 'А' && r <= 'я') || r == 'Ё' || r == 'ё' {
+			hasCyrillic = true
+			break
+		}
+	}
+	
+	if !hasCyrillic {
+		return fmt.Errorf("text must contain Bulgarian Cyrillic characters")
+	}
+	
+	return nil
+}
+
+// ListVoices returns available Bulgarian voice variants
+func ListVoices() []string {
+	return []string{
+		"bg",      // Default Bulgarian voice
+		"bg+m1",   // Bulgarian male voice 1
+		"bg+m2",   // Bulgarian male voice 2
+		"bg+m3",   // Bulgarian male voice 3
+		"bg+f1",   // Bulgarian female voice 1
+		"bg+f2",   // Bulgarian female voice 2
+		"bg+f3",   // Bulgarian female voice 3
+	}
+}
+
+// ConvertWAVToMP3 converts a WAV file to MP3 using ffmpeg
+func ConvertWAVToMP3(wavFile, mp3File string) error {
+	// Check if ffmpeg is installed
+	if err := exec.Command("ffmpeg", "-version").Run(); err != nil {
+		return fmt.Errorf("ffmpeg is not installed or not in PATH: %w", err)
+	}
+	
+	cmd := exec.Command("ffmpeg", "-i", wavFile, "-acodec", "mp3", "-y", mp3File)
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("ffmpeg conversion failed: %w\nOutput: %s", err, string(output))
+	}
+	
+	return nil
+}
+
+// GenerateMP3 generates an MP3 file for the given Bulgarian text
+func (e *ESpeak) GenerateMP3(text string, outputFile string) error {
+	// Generate temporary WAV file
+	tempWAV := strings.TrimSuffix(outputFile, filepath.Ext(outputFile)) + "_temp.wav"
+	
+	// Generate WAV
+	if err := e.GenerateAudio(text, tempWAV); err != nil {
+		return err
+	}
+	
+	// Convert to MP3
+	if err := ConvertWAVToMP3(tempWAV, outputFile); err != nil {
+		// Clean up temporary file
+		os.Remove(tempWAV)
+		return err
+	}
+	
+	// Clean up temporary file
+	return os.Remove(tempWAV)
+}
\ No newline at end of file
diff --git a/internal/audio/espeak_provider.go b/internal/audio/espeak_provider.go
new file mode 100644
index 0000000..177e2a6
--- /dev/null
+++ b/internal/audio/espeak_provider.go
@@ -0,0 +1,65 @@
+package audio
+
+import (
+	"context"
+	"path/filepath"
+	"strings"
+)
+
+// ESpeakProvider implements Provider interface for espeak-ng
+type ESpeakProvider struct {
+	espeak *ESpeak
+	format string
+}
+
+// NewESpeakProvider creates a new espeak-ng provider
+func NewESpeakProvider(config *ESpeakConfig) (Provider, error) {
+	espeak, err := New(config)
+	if err != nil {
+		return nil, err
+	}
+	
+	return &ESpeakProvider{
+		espeak: espeak,
+		format: "mp3", // default format
+	}, nil
+}
+
+// GenerateAudio generates audio using espeak-ng
+func (p *ESpeakProvider) GenerateAudio(ctx context.Context, text string, outputFile string) error {
+	// Validate Bulgarian text
+	if err := ValidateBulgarianText(text); err != nil {
+		return err
+	}
+	
+	// Determine format from output file extension
+	ext := strings.ToLower(filepath.Ext(outputFile))
+	
+	switch ext {
+	case ".mp3":
+		return p.espeak.GenerateMP3(text, outputFile)
+	case ".wav":
+		return p.espeak.GenerateAudio(text, outputFile)
+	default:
+		// Default to MP3 if extension is unclear
+		if !strings.HasSuffix(outputFile, ".mp3") {
+			outputFile += ".mp3"
+		}
+		return p.espeak.GenerateMP3(text, outputFile)
+	}
+}
+
+// Name returns the provider name
+func (p *ESpeakProvider) Name() string {
+	return "espeak-ng"
+}
+
+// IsAvailable checks if espeak-ng is installed
+func (p *ESpeakProvider) IsAvailable() error {
+	return checkESpeakInstalled()
+}
+
+// SetFormat sets the output format preference
+func (p *ESpeakProvider) SetFormat(format string) {
+	p.format = format
+}
\ No newline at end of file
diff --git a/internal/audio/espeak_test.go b/internal/audio/espeak_test.go
new file mode 100644
index 0000000..66c45f5
--- /dev/null
+++ b/internal/audio/espeak_test.go
@@ -0,0 +1,198 @@
+package audio
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestValidateBulgarianText(t *testing.T) {
+	tests := []struct {
+		name    string
+		text    string
+		wantErr bool
+	}{
+		{
+			name:    "valid Bulgarian word",
+			text:    "ябълка",
+			wantErr: false,
+		},
+		{
+			name:    "valid Bulgarian phrase",
+			text:    "добър ден",
+			wantErr: false,
+		},
+		{
+			name:    "empty string",
+			text:    "",
+			wantErr: true,
+		},
+		{
+			name:    "only Latin characters",
+			text:    "apple",
+			wantErr: true,
+		},
+		{
+			name:    "mixed Cyrillic and Latin",
+			text:    "ябълка apple",
+			wantErr: false, // Contains at least one Cyrillic
+		},
+		{
+			name:    "numbers only",
+			text:    "12345",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := ValidateBulgarianText(tt.text)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("ValidateBulgarianText() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestListVoices(t *testing.T) {
+	voices := ListVoices()
+	
+	if len(voices) == 0 {
+		t.Error("ListVoices() returned empty slice")
+	}
+	
+	// Check for expected voices
+	expectedVoices := []string{"bg", "bg+m1", "bg+f1"}
+	for _, expected := range expectedVoices {
+		found := false
+		for _, voice := range voices {
+			if voice == expected {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("Expected voice %s not found in list", expected)
+		}
+	}
+}
+
+func TestDefaultConfig(t *testing.T) {
+	config := DefaultConfig()
+	
+	if config == nil {
+		t.Fatal("DefaultConfig() returned nil")
+	}
+	
+	if config.Voice != "bg" {
+		t.Errorf("Expected default voice 'bg', got '%s'", config.Voice)
+	}
+	
+	if config.Speed != 150 {
+		t.Errorf("Expected default speed 150, got %d", config.Speed)
+	}
+	
+	if config.OutputDir != "./" {
+		t.Errorf("Expected default output dir './', got '%s'", config.OutputDir)
+	}
+}
+
+func TestNew(t *testing.T) {
+	// This test will fail if espeak-ng is not installed
+	// We'll skip it in that case
+	espeak, err := New(nil)
+	if err != nil {
+		if checkESpeakInstalled() != nil {
+			t.Skip("espeak-ng not installed, skipping test")
+		}
+		t.Fatalf("New() failed: %v", err)
+	}
+	
+	if espeak == nil {
+		t.Fatal("New() returned nil ESpeak instance")
+	}
+	
+	if espeak.config == nil {
+		t.Fatal("ESpeak instance has nil config")
+	}
+}
+
+func TestSetSpeed(t *testing.T) {
+	config := DefaultConfig()
+	espeak := &ESpeak{config: config}
+	
+	tests := []struct {
+		input    int
+		expected int
+	}{
+		{150, 150},     // Normal speed
+		{50, 80},       // Below minimum
+		{500, 450},     // Above maximum
+		{200, 200},     // Valid speed
+	}
+	
+	for _, tt := range tests {
+		espeak.SetSpeed(tt.input)
+		if espeak.config.Speed != tt.expected {
+			t.Errorf("SetSpeed(%d) resulted in speed %d, expected %d",
+				tt.input, espeak.config.Speed, tt.expected)
+		}
+	}
+}
+
+func TestGenerateAudio_InvalidInput(t *testing.T) {
+	// Skip if espeak-ng not installed
+	if checkESpeakInstalled() != nil {
+		t.Skip("espeak-ng not installed, skipping test")
+	}
+	
+	espeak, err := New(nil)
+	if err != nil {
+		t.Fatalf("Failed to create ESpeak: %v", err)
+	}
+	
+	// Test with empty text
+	err = espeak.GenerateAudio("", "test.wav")
+	if err == nil {
+		t.Error("GenerateAudio() with empty text should return error")
+	}
+}
+
+func TestGenerateAudio_Integration(t *testing.T) {
+	// Skip if espeak-ng not installed
+	if checkESpeakInstalled() != nil {
+		t.Skip("espeak-ng not installed, skipping integration test")
+	}
+	
+	// Create temporary directory
+	tempDir := t.TempDir()
+	
+	config := &ESpeakConfig{
+		Voice:     "bg",
+		Speed:     150,
+		OutputDir: tempDir,
+	}
+	
+	espeak, err := New(config)
+	if err != nil {
+		t.Fatalf("Failed to create ESpeak: %v", err)
+	}
+	
+	// Generate audio file
+	outputFile := filepath.Join(tempDir, "test.wav")
+	err = espeak.GenerateAudio("ябълка", outputFile)
+	if err != nil {
+		t.Fatalf("GenerateAudio() failed: %v", err)
+	}
+	
+	// Check if file was created
+	info, err := os.Stat(outputFile)
+	if err != nil {
+		t.Fatalf("Output file not created: %v", err)
+	}
+	
+	// Check file size (WAV file should have some content)
+	if info.Size() == 0 {
+		t.Error("Output file is empty")
+	}
+}
\ No newline at end of file
diff --git a/internal/audio/openai_provider.go b/internal/audio/openai_provider.go
new file mode 100644
index 0000000..9efbcd2
--- /dev/null
+++ b/internal/audio/openai_provider.go
@@ -0,0 +1,219 @@
+package audio
+
+import (
+	"context"
+	"crypto/md5"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	
+	"github.com/sashabaranov/go-openai"
+)
+
+// OpenAIProvider implements Provider interface for OpenAI TTS
+type OpenAIProvider struct {
+	client      *openai.Client
+	config      *Config
+	cacheDir    string
+	enableCache bool
+}
+
+// NewOpenAIProvider creates a new OpenAI TTS provider
+func NewOpenAIProvider(config *Config) (Provider, error) {
+	if config.OpenAIKey == "" {
+		return nil, fmt.Errorf("OpenAI API key is required")
+	}
+	
+	client := openai.NewClient(config.OpenAIKey)
+	
+	provider := &OpenAIProvider{
+		client:      client,
+		config:      config,
+		cacheDir:    config.CacheDir,
+		enableCache: config.EnableCache,
+	}
+	
+	// Create cache directory if caching is enabled
+	if provider.enableCache && provider.cacheDir != "" {
+		if err := os.MkdirAll(provider.cacheDir, 0755); err != nil {
+			return nil, fmt.Errorf("failed to create cache directory: %w", err)
+		}
+	}
+	
+	return provider, nil
+}
+
+// GenerateAudio generates audio using OpenAI TTS
+func (p *OpenAIProvider) GenerateAudio(ctx context.Context, text string, outputFile string) error {
+	// Validate Bulgarian text
+	if err := ValidateBulgarianText(text); err != nil {
+		return err
+	}
+	
+	// Check cache first
+	if p.enableCache {
+		cacheFile := p.getCacheFilePath(text)
+		if _, err := os.Stat(cacheFile); err == nil {
+			// Cache hit - copy cached file
+			return p.copyFile(cacheFile, outputFile)
+		}
+	}
+	
+	// Prepare the TTS request
+	req := openai.CreateSpeechRequest{
+		Model: openai.SpeechModel(p.config.OpenAIModel),
+		Input: text,
+		Voice: openai.SpeechVoice(p.config.OpenAIVoice),
+		Speed: p.config.OpenAISpeed,
+	}
+	
+	// Determine response format based on output file extension
+	ext := strings.ToLower(filepath.Ext(outputFile))
+	switch ext {
+	case ".mp3":
+		req.ResponseFormat = openai.SpeechResponseFormatMp3
+	case ".wav":
+		req.ResponseFormat = openai.SpeechResponseFormatWav
+	case ".opus":
+		req.ResponseFormat = openai.SpeechResponseFormatOpus
+	case ".aac":
+		req.ResponseFormat = openai.SpeechResponseFormatAac
+	case ".flac":
+		req.ResponseFormat = openai.SpeechResponseFormatFlac
+	default:
+		req.ResponseFormat = openai.SpeechResponseFormatMp3
+		if !strings.HasSuffix(outputFile, ".mp3") {
+			outputFile += ".mp3"
+		}
+	}
+	
+	// Make the API call
+	response, err := p.client.CreateSpeech(ctx, req)
+	if err != nil {
+		return fmt.Errorf("OpenAI TTS API error: %w", err)
+	}
+	defer response.Close()
+	
+	// Ensure output directory exists
+	dir := filepath.Dir(outputFile)
+	if dir != "" && dir != "." {
+		if err := os.MkdirAll(dir, 0755); err != nil {
+			return fmt.Errorf("failed to create output directory: %w", err)
+		}
+	}
+	
+	// Create output file
+	out, err := os.Create(outputFile)
+	if err != nil {
+		return fmt.Errorf("failed to create output file: %w", err)
+	}
+	defer out.Close()
+	
+	// Copy the audio data
+	written, err := io.Copy(out, response)
+	if err != nil {
+		return fmt.Errorf("failed to write audio file: %w", err)
+	}
+	
+	if written == 0 {
+		return fmt.Errorf("no audio data received from OpenAI")
+	}
+	
+	// Cache the result if caching is enabled
+	if p.enableCache {
+		cacheFile := p.getCacheFilePath(text)
+		_ = p.copyFile(outputFile, cacheFile) // Ignore cache errors
+	}
+	
+	return nil
+}
+
+// Name returns the provider name
+func (p *OpenAIProvider) Name() string {
+	return "openai"
+}
+
+// IsAvailable checks if the OpenAI API is accessible
+func (p *OpenAIProvider) IsAvailable() error {
+	if p.config.OpenAIKey == "" {
+		return fmt.Errorf("OpenAI API key not configured")
+	}
+	
+	// We could make a test API call here, but that would use credits
+	// For now, just check that we have a key
+	return nil
+}
+
+// getCacheFilePath generates a cache file path for the given text
+func (p *OpenAIProvider) getCacheFilePath(text string) string {
+	// Create a hash of the text and settings
+	h := md5.New()
+	h.Write([]byte(text))
+	h.Write([]byte(p.config.OpenAIModel))
+	h.Write([]byte(p.config.OpenAIVoice))
+	h.Write([]byte(fmt.Sprintf("%.2f", p.config.OpenAISpeed)))
+	hash := hex.EncodeToString(h.Sum(nil))
+	
+	// Use first 2 chars as subdirectory for better file system performance
+	subdir := hash[:2]
+	filename := hash[2:] + ".mp3"
+	
+	return filepath.Join(p.cacheDir, subdir, filename)
+}
+
+// copyFile copies a file from src to dst
+func (p *OpenAIProvider) copyFile(src, dst string) error {
+	// Ensure destination directory exists
+	dir := filepath.Dir(dst)
+	if dir != "" && dir != "." {
+		if err := os.MkdirAll(dir, 0755); err != nil {
+			return err
+		}
+	}
+	
+	source, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer source.Close()
+	
+	destination, err := os.Create(dst)
+	if err != nil {
+		return err
+	}
+	defer destination.Close()
+	
+	_, err = io.Copy(destination, source)
+	return err
+}
+
+// ClearCache removes all cached audio files
+func (p *OpenAIProvider) ClearCache() error {
+	if p.cacheDir == "" {
+		return nil
+	}
+	return os.RemoveAll(p.cacheDir)
+}
+
+// GetCacheStats returns cache statistics
+func (p *OpenAIProvider) GetCacheStats() (fileCount int, totalSize int64, err error) {
+	if !p.enableCache || p.cacheDir == "" {
+		return 0, 0, nil
+	}
+	
+	err = filepath.Walk(p.cacheDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if !info.IsDir() {
+			fileCount++
+			totalSize += info.Size()
+		}
+		return nil
+	})
+	
+	return fileCount, totalSize, err
+}
\ No newline at end of file
diff --git a/internal/audio/provider.go b/internal/audio/provider.go
new file mode 100644
index 0000000..5b8c336
--- /dev/null
+++ b/internal/audio/provider.go
@@ -0,0 +1,139 @@
+package audio
+
+import (
+	"context"
+	"fmt"
+)
+
+// Provider defines the interface for text-to-speech providers
+type Provider interface {
+	// GenerateAudio generates audio from text and saves it to the specified file
+	GenerateAudio(ctx context.Context, text string, outputFile string) error
+	
+	// Name returns the provider name
+	Name() string
+	
+	// IsAvailable checks if the provider is properly configured and available
+	IsAvailable() error
+}
+
+// Config holds common configuration for audio providers
+type Config struct {
+	Provider     string // Provider name: "espeak" or "openai"
+	OutputDir    string // Directory for output files
+	OutputFormat string // Output format: "mp3" or "wav"
+	
+	// ESpeak-specific settings
+	ESpeakVoice     string
+	ESpeakSpeed     int
+	ESpeakPitch     int
+	ESpeakAmplitude int
+	ESpeakWordGap   int
+	
+	// OpenAI-