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-specific settings
+	OpenAIKey      string
+	OpenAIModel    string // "tts-1" or "tts-1-hd"
+	OpenAIVoice    string // "alloy", "echo", "fable", "onyx", "nova", "shimmer"
+	OpenAISpeed    float64 // 0.25 to 4.0
+	
+	// Caching settings
+	EnableCache bool
+	CacheDir    string
+}
+
+// DefaultConfig returns default configuration
+func DefaultProviderConfig() *Config {
+	return &Config{
+		Provider:        "espeak",
+		OutputDir:       "./",
+		OutputFormat:    "mp3",
+		ESpeakVoice:     "bg",
+		ESpeakSpeed:     150,
+		ESpeakPitch:     50,
+		ESpeakAmplitude: 100,
+		ESpeakWordGap:   0,
+		OpenAIModel:     "tts-1",
+		OpenAIVoice:     "nova",
+		OpenAISpeed:     1.0,
+		EnableCache:     true,
+		CacheDir:        "./.audio_cache",
+	}
+}
+
+// NewProvider creates the appropriate audio provider based on configuration
+func NewProvider(config *Config) (Provider, error) {
+	if config == nil {
+		config = DefaultProviderConfig()
+	}
+	
+	switch config.Provider {
+	case "espeak", "espeak-ng":
+		espeakConfig := &ESpeakConfig{
+			Voice:     config.ESpeakVoice,
+			Speed:     config.ESpeakSpeed,
+			Pitch:     config.ESpeakPitch,
+			Amplitude: config.ESpeakAmplitude,
+			WordGap:   config.ESpeakWordGap,
+			OutputDir: config.OutputDir,
+		}
+		return NewESpeakProvider(espeakConfig)
+		
+	case "openai":
+		if config.OpenAIKey == "" {
+			return nil, fmt.Errorf("OpenAI API key is required")
+		}
+		return NewOpenAIProvider(config)
+		
+	default:
+		return nil, fmt.Errorf("unknown audio provider: %s", config.Provider)
+	}
+}
+
+// ProviderWithFallback wraps a primary provider with a fallback option
+type ProviderWithFallback struct {
+	primary   Provider
+	fallback  Provider
+}
+
+// NewProviderWithFallback creates a provider that falls back to secondary if primary fails
+func NewProviderWithFallback(primary, fallback Provider) Provider {
+	return &ProviderWithFallback{
+		primary:  primary,
+		fallback: fallback,
+	}
+}
+
+// GenerateAudio tries primary provider first, falls back to secondary on error
+func (p *ProviderWithFallback) GenerateAudio(ctx context.Context, text string, outputFile string) error {
+	err := p.primary.GenerateAudio(ctx, text, outputFile)
+	if err != nil {
+		// Log the primary error
+		fmt.Printf("Primary provider (%s) failed: %v. Falling back to %s\n", 
+			p.primary.Name(), err, p.fallback.Name())
+		
+		// Try fallback
+		return p.fallback.GenerateAudio(ctx, text, outputFile)
+	}
+	return nil
+}
+
+// Name returns the provider name
+func (p *ProviderWithFallback) Name() string {
+	return fmt.Sprintf("%s (fallback: %s)", p.primary.Name(), p.fallback.Name())
+}
+
+// IsAvailable checks if at least one provider is available
+func (p *ProviderWithFallback) IsAvailable() error {
+	primaryErr := p.primary.IsAvailable()
+	if primaryErr == nil {
+		return nil
+	}
+	
+	fallbackErr := p.fallback.IsAvailable()
+	if fallbackErr == nil {
+		return nil
+	}
+	
+	return fmt.Errorf("both providers unavailable: primary=%v, fallback=%v", 
+		primaryErr, fallbackErr)
+}
\ No newline at end of file
diff --git a/internal/config/doc.go b/internal/config/doc.go
new file mode 100644
index 0000000..b616b99
--- /dev/null
+++ b/internal/config/doc.go
@@ -0,0 +1,3 @@
+// Package config provides configuration management for the bulg
+// application using viper for flexible configuration options.
+package config
\ No newline at end of file
diff --git a/internal/image/doc.go b/internal/image/doc.go
new file mode 100644
index 0000000..2fb3723
--- /dev/null
+++ b/internal/image/doc.go
@@ -0,0 +1,3 @@
+// Package image provides image search functionality to find
+// representative images for Bulgarian words from various APIs.
+package image
\ No newline at end of file
diff --git a/internal/image/download.go b/internal/image/download.go
new file mode 100644
index 0000000..f684260
--- /dev/null
+++ b/internal/image/download.go
@@ -0,0 +1,244 @@
+package image
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// DownloadOptions configures image download behavior
+type DownloadOptions struct {
+	OutputDir       string   // Directory to save images
+	OverwriteExisting bool   // Whether to overwrite existing files
+	CreateDir       bool     // Create output directory if it doesn't exist
+	FileNamePattern string   // Pattern for file naming (e.g., "{word}_{source}")
+	MaxSizeBytes    int64    // Maximum file size to download (0 = no limit)
+}
+
+// DefaultDownloadOptions returns sensible defaults for image downloads
+func DefaultDownloadOptions() *DownloadOptions {
+	return &DownloadOptions{
+		OutputDir:       "./images",
+		OverwriteExisting: false,
+		CreateDir:       true,
+		FileNamePattern: "{word}_{source}",
+		MaxSizeBytes:    10 * 1024 * 1024, // 10MB
+	}
+}
+
+// Downloader handles image downloads from search results
+type Downloader struct {
+	searcher ImageSearcher
+	options  *DownloadOptions
+}
+
+// NewDownloader creates a new image downloader
+func NewDownloader(searcher ImageSearcher, options *DownloadOptions) *Downloader {
+	if options == nil {
+		options = DefaultDownloadOptions()
+	}
+	return &Downloader{
+		searcher: searcher,
+		options:  options,
+	}
+}
+
+// DownloadImage downloads a single image to the specified path
+func (d *Downloader) DownloadImage(ctx context.Context, result *SearchResult, outputPath string) error {
+	// Ensure directory exists
+	dir := filepath.Dir(outputPath)
+	if dir != "" && dir != "." {
+		if err := os.MkdirAll(dir, 0755); err != nil {
+			return fmt.Errorf("failed to create directory: %w", err)
+		}
+	}
+	
+	// Check if file already exists
+	if !d.options.OverwriteExisting {
+		if _, err := os.Stat(outputPath); err == nil {
+			return fmt.Errorf("file already exists: %s", outputPath)
+		}
+	}
+	
+	// Download the image
+	reader, err := d.searcher.Download(ctx, result.URL)
+	if err != nil {
+		return fmt.Errorf("failed to download image: %w", err)
+	}
+	defer reader.Close()
+	
+	// Create output file
+	file, err := os.Create(outputPath)
+	if err != nil {
+		return fmt.Errorf("failed to create file: %w", err)
+	}
+	defer file.Close()
+	
+	// Copy with size limit if specified
+	var written int64
+	if d.options.MaxSizeBytes > 0 {
+		written, err = io.CopyN(file, reader, d.options.MaxSizeBytes)
+		if err != nil && err != io.EOF {
+			os.Remove(outputPath) // Clean up on error
+			return fmt.Errorf("failed to write file: %w", err)
+		}
+		
+		// Check if we hit the size limit
+		if written == d.options.MaxSizeBytes {
+			// Try to read one more byte to see if file is larger
+			if _, err := reader.Read(make([]byte, 1)); err != io.EOF {
+				os.Remove(outputPath) // Clean up
+				return fmt.Errorf("image exceeds maximum size of %d bytes", d.options.MaxSizeBytes)
+			}
+		}
+	} else {
+		written, err = io.Copy(file, reader)
+		if err != nil {
+			os.Remove(outputPath) // Clean up on error
+			return fmt.Errorf("failed to write file: %w", err)
+		}
+	}
+	
+	// Save attribution if required
+	if attribution := d.searcher.GetAttribution(result); attribution != "" {
+		attrPath := strings.TrimSuffix(outputPath, filepath.Ext(outputPath)) + "_attribution.txt"
+		if err := os.WriteFile(attrPath, []byte(attribution), 0644); err != nil {
+			// Non-fatal error - log but don't fail the download
+			fmt.Fprintf(os.Stderr, "Warning: failed to save attribution: %v\n", err)
+		}
+	}
+	
+	return nil
+}
+
+// DownloadBestMatch downloads the best matching image for a query
+func (d *Downloader) DownloadBestMatch(ctx context.Context, query string) (*SearchResult, string, error) {
+	// Search for images
+	opts := DefaultSearchOptions(query)
+	opts.PerPage = 5 // Get top 5 results
+	
+	results, err := d.searcher.Search(ctx, opts)
+	if err != nil {
+		return nil, "", fmt.Errorf("search failed: %w", err)
+	}
+	
+	if len(results) == 0 {
+		return nil, "", fmt.Errorf("no images found for query: %s", query)
+	}
+	
+	// Try to download the first available image
+	for i, result := range results {
+		// Generate filename
+		filename := d.generateFileName(query, &result, i)
+		outputPath := filepath.Join(d.options.OutputDir, filename)
+		
+		// Try to download
+		err := d.DownloadImage(ctx, &result, outputPath)
+		if err == nil {
+			return &result, outputPath, nil
+		}
+		
+		// Log error and try next
+		fmt.Fprintf(os.Stderr, "Warning: failed to download image %d: %v\n", i+1, err)
+	}
+	
+	return nil, "", fmt.Errorf("failed to download any images for query: %s", query)
+}
+
+// generateFileName creates a filename based on the pattern
+func (d *Downloader) generateFileName(word string, result *SearchResult, index int) string {
+	// Start with the pattern
+	filename := d.options.FileNamePattern
+	
+	// Replace placeholders
+	filename = strings.ReplaceAll(filename, "{word}", sanitizeFileName(word))
+	filename = strings.ReplaceAll(filename, "{source}", result.Source)
+	filename = strings.ReplaceAll(filename, "{id}", result.ID)
+	filename = strings.ReplaceAll(filename, "{index}", fmt.Sprintf("%d", index))
+	
+	// Determine extension from URL
+	ext := filepath.Ext(result.URL)
+	if ext == "" || len(ext) > 5 { // Probably not a real extension
+		ext = ".jpg" // Default to jpg
+	}
+	
+	// Add extension if not present
+	if filepath.Ext(filename) == "" {
+		filename += ext
+	}
+	
+	return filename
+}
+
+// sanitizeFileName removes or replaces characters that are problematic in filenames
+func sanitizeFileName(name string) string {
+	// Replace common problematic characters
+	replacer := strings.NewReplacer(
+		"/", "_",
+		"\\", "_",
+		":", "_",
+		"*", "_",
+		"?", "_",
+		"\"", "_",
+		"<", "_",
+		">", "_",
+		"|", "_",
+		" ", "_",
+		".", "_",
+	)
+	
+	sanitized := replacer.Replace(name)
+	
+	// Ensure the filename is not too long
+	if len(sanitized) > 50 {
+		sanitized = sanitized[:50]
+	}
+	
+	return sanitized
+}
+
+// DownloadMultiple downloads multiple images for a query
+func (d *Downloader) DownloadMultiple(ctx context.Context, query string, count int) ([]string, error) {
+	// Search for images
+	opts := DefaultSearchOptions(query)
+	opts.PerPage = count * 2 // Get extra in case some fail
+	
+	results, err := d.searcher.Search(ctx, opts)
+	if err != nil {
+		return nil, fmt.Errorf("search failed: %w", err)
+	}
+	
+	if len(results) == 0 {
+		return nil, fmt.Errorf("no images found for query: %s", query)
+	}
+	
+	// Download up to 'count' images
+	var downloaded []string
+	for i, result := range results {
+		if len(downloaded) >= count {
+			break
+		}
+		
+		// Generate filename
+		filename := d.generateFileName(query, &result, i)
+		outputPath := filepath.Join(d.options.OutputDir, filename)
+		
+		// Try to download
+		err := d.DownloadImage(ctx, &result, outputPath)
+		if err == nil {
+			downloaded = append(downloaded, outputPath)
+		} else {
+			// Log error and continue
+			fmt.Fprintf(os.Stderr, "Warning: failed to download image %d: %v\n", i+1, err)
+		}
+	}
+	
+	if len(downloaded) == 0 {
+		return nil, fmt.Errorf("failed to download any images for query: %s", query)
+	}
+	
+	return downloaded, nil
+}
\ No newline at end of file
diff --git a/internal/image/pixabay.go b/internal/image/pixabay.go
new file mode 100644
index 0000000..7b714b1
--- /dev/null
+++ b/internal/image/pixabay.go
@@ -0,0 +1,231 @@
+package image
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"time"
+)
+
+const (
+	pixabayAPIURL = "https://pixabay.com/api/"
+	pixabayTimeout = 30 * time.Second
+)
+
+// PixabayClient implements ImageSearcher for Pixabay API
+type PixabayClient struct {
+	apiKey     string
+	httpClient *http.Client
+	rateLimit  *rateLimiter
+}
+
+// pixabayResponse represents the API response structure
+type pixabayResponse struct {
+	Total     int            `json:"total"`
+	TotalHits int            `json:"totalHits"`
+	Hits      []pixabayImage `json:"hits"`
+}
+
+// pixabayImage represents a single image in the response
+type pixabayImage struct {
+	ID               int    `json:"id"`
+	PageURL          string `json:"pageURL"`
+	Type             string `json:"type"`
+	Tags             string `json:"tags"`
+	PreviewURL       string `json:"previewURL"`
+	PreviewWidth     int    `json:"previewWidth"`
+	PreviewHeight    int    `json:"previewHeight"`
+	WebformatURL     string `json:"webformatURL"`
+	WebformatWidth   int    `json:"webformatWidth"`
+	WebformatHeight  int    `json:"webformatHeight"`
+	LargeImageURL    string `json:"largeImageURL"`
+	ImageWidth       int    `json:"imageWidth"`
+	ImageHeight      int    `json:"imageHeight"`
+	Views            int    `json:"views"`
+	Downloads        int    `json:"downloads"`
+	Collections      int    `json:"collections"`
+	Likes            int    `json:"likes"`
+	Comments         int    `json:"comments"`
+	UserID           int    `json:"user_id"`
+	User             string `json:"user"`
+	UserImageURL     string `json:"userImageURL"`
+}
+
+// rateLimiter implements simple rate limiting
+type rateLimiter struct {
+	requestsPerMinute int
+	requests         []time.Time
+}
+
+func newRateLimiter(rpm int) *rateLimiter {
+	return &rateLimiter{
+		requestsPerMinute: rpm,
+		requests:         make([]time.Time, 0, rpm),
+	}
+}
+
+func (rl *rateLimiter) wait() {
+	now := time.Now()
+	
+	// Remove requests older than 1 minute
+	cutoff := now.Add(-1 * time.Minute)
+	i := 0
+	for i < len(rl.requests) && rl.requests[i].Before(cutoff) {
+		i++
+	}
+	rl.requests = rl.requests[i:]
+	
+	// If we're at the limit, wait
+	if len(rl.requests) >= rl.requestsPerMinute {
+		oldestRequest := rl.requests[0]
+		waitDuration := oldestRequest.Add(1 * time.Minute).Sub(now)
+		if waitDuration > 0 {
+			time.Sleep(waitDuration)
+		}
+	}
+	
+	// Record this request
+	rl.requests = append(rl.requests, now)
+}
+
+// NewPixabayClient creates a new Pixabay API client
+func NewPixabayClient(apiKey string) *PixabayClient {
+	return &PixabayClient{
+		apiKey: apiKey,
+		httpClient: &http.Client{
+			Timeout: pixabayTimeout,
+		},
+		rateLimit: newRateLimiter(100), // 100 requests per minute
+	}
+}
+
+// Search performs an image search on Pixabay
+func (p *PixabayClient) Search(ctx context.Context, opts *SearchOptions) ([]SearchResult, error) {
+	// Apply rate limiting
+	p.rateLimit.wait()
+	
+	// Build query parameters
+	params := url.Values{}
+	if p.apiKey != "" {
+		params.Set("key", p.apiKey)
+	}
+	params.Set("q", opts.Query)
+	params.Set("lang", opts.Language)
+	params.Set("image_type", opts.ImageType)
+	params.Set("safesearch", fmt.Sprintf("%t", opts.SafeSearch))
+	params.Set("per_page", fmt.Sprintf("%d", opts.PerPage))
+	params.Set("page", fmt.Sprintf("%d", opts.Page))
+	
+	if opts.Orientation != "all" && opts.Orientation != "" {
+		params.Set("orientation", opts.Orientation)
+	}
+	
+	// Make request
+	reqURL := pixabayAPIURL + "?" + params.Encode()
+	req, err := http.NewRequestWithContext(ctx, "GET", reqURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+	
+	resp, err := p.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+	
+	// Check status code
+	if resp.StatusCode == http.StatusTooManyRequests {
+		return nil, &RateLimitError{
+			Provider:     "pixabay",
+			RetryAfter:   60,
+			LimitPerHour: 5000,
+		}
+	}
+	
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, &SearchError{
+			Provider: "pixabay",
+			Code:     fmt.Sprintf("%d", resp.StatusCode),
+			Message:  string(body),
+		}
+	}
+	
+	// Parse response
+	var pixResp pixabayResponse
+	if err := json.NewDecoder(resp.Body).Decode(&pixResp); err != nil {
+		return nil, fmt.Errorf("failed to decode response: %w", err)
+	}
+	
+	// Convert to SearchResult
+	results := make([]SearchResult, 0, len(pixResp.Hits))
+	for _, hit := range pixResp.Hits {
+		results = append(results, SearchResult{
+			ID:           fmt.Sprintf("%d", hit.ID),
+			URL:          hit.WebformatURL,
+			ThumbnailURL: hit.PreviewURL,
+			Width:        hit.WebformatWidth,
+			Height:       hit.WebformatHeight,
+			Description:  hit.Tags,
+			Attribution:  fmt.Sprintf("Image by %s from Pixabay", hit.User),
+			Source:       "pixabay",
+		})
+	}
+	
+	return results, nil
+}
+
+// Download downloads an image from the given URL
+func (p *PixabayClient) Download(ctx context.Context, imageURL string) (io.ReadCloser, error) {
+	req, err := http.NewRequestWithContext(ctx, "GET", imageURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create download request: %w", err)
+	}
+	
+	resp, err := p.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("download failed: %w", err)
+	}
+	
+	if resp.StatusCode != http.StatusOK {
+		resp.Body.Close()
+		return nil, fmt.Errorf("download failed with status %d", resp.StatusCode)
+	}
+	
+	return resp.Body, nil
+}
+
+// GetAttribution returns the required attribution text for an image
+func (p *PixabayClient) GetAttribution(result *SearchResult) string {
+	if p.apiKey == "" {
+		// Without API key, attribution is required
+		return result.Attribution
+	}
+	// With API key, attribution is optional but recommended
+	return ""
+}
+
+// Name returns the name of the search provider
+func (p *PixabayClient) Name() string {
+	return "pixabay"
+}
+
+
+// SearchWithTranslation performs a search with automatic translation
+func (p *PixabayClient) SearchWithTranslation(ctx context.Context, opts *SearchOptions) ([]SearchResult, error) {
+	// Try with translated query first
+	translatedQuery := translateBulgarianQuery(opts.Query)
+	translatedOpts := *opts
+	translatedOpts.Query = translatedQuery
+	
+	results, err := p.Search(ctx, &translatedOpts)
+	if err != nil || len(results) == 0 {
+		// Fall back to original query
+		return p.Search(ctx, opts)
+	}
+	
+	return results, nil
+}
\ No newline at end of file
diff --git a/internal/image/search.go b/internal/image/search.go
new file mode 100644
index 0000000..acc9dc8
--- /dev/null
+++ b/internal/image/search.go
@@ -0,0 +1,87 @@
+package image
+
+import (
+	"context"
+	"io"
+)
+
+// SearchResult represents a single image search result
+type SearchResult struct {
+	ID           string   // Unique identifier
+	URL          string   // Direct URL to the image
+	ThumbnailURL string   // URL to thumbnail version
+	Width        int      // Image width in pixels
+	Height       int      // Image height in pixels
+	Description  string   // Image description or tags
+	Attribution  string   // Attribution text if required
+	Source       string   // Source provider (e.g., "pixabay", "unsplash")
+}
+
+// SearchOptions configures the image search
+type SearchOptions struct {
+	Query       string   // Search query (Bulgarian word)
+	Language    string   // Language code (default: "bg")
+	SafeSearch  bool     // Enable safe search filtering
+	PerPage     int      // Number of results per page
+	Page        int      // Page number (1-based)
+	ImageType   string   // Type: "photo", "illustration", "vector", "all"
+	Orientation string   // Orientation: "horizontal", "vertical", "all"
+}
+
+// DefaultSearchOptions returns sensible defaults for Bulgarian word searches
+func DefaultSearchOptions(query string) *SearchOptions {
+	return &SearchOptions{
+		Query:       query,
+		Language:    "bg",
+		SafeSearch:  true,
+		PerPage:     10,
+		Page:        1,
+		ImageType:   "photo",
+		Orientation: "all",
+	}
+}
+
+// ImageSearcher defines the interface for image search providers
+type ImageSearcher interface {
+	// Search performs an image search with the given options
+	Search(ctx context.Context, opts *SearchOptions) ([]SearchResult, error)
+	
+	// Download downloads an image from the given URL
+	Download(ctx context.Context, url string) (io.ReadCloser, error)
+	
+	// GetAttribution returns the required attribution text for an image
+	GetAttribution(result *SearchResult) string
+	
+	// Name returns the name of the search provider
+	Name() string
+}
+
+// SearchError represents an error from an image search provider
+type SearchError struct {
+	Provider string
+	Code     string
+	Message  string
+}
+
+func (e *SearchError) Error() string {
+	return e.Provider + ": " + e.Message
+}
+
+// RateLimitError indicates that the API rate limit has been exceeded
+type RateLimitError struct {
+	Provider      string
+	RetryAfter    int // Seconds to wait before retry
+	LimitPerHour  int
+	LimitPerDay   int
+}
+
+func (e *RateLimitError) Error() string {
+	return e.Provider + ": rate limit exceeded"
+}
+
+// DownloadImage is a utility function to download an image to a file
+func DownloadImage(ctx context.Context, searcher ImageSearcher, url string, outputPath string) error {
+	// Implementation will be in a separate download.go file
+	// This is just the interface definition
+	return nil
+}
\ No newline at end of file
diff --git a/internal/image/search_test.go b/internal/image/search_test.go
new file mode 100644
index 0000000..b7018d9
--- /dev/null
+++ b/internal/image/search_test.go
@@ -0,0 +1,146 @@
+package image
+
+import (
+	"context"
+	"io"
+	"strings"
+	"testing"
+)
+
+// mockSearcher implements ImageSearcher for testing
+type mockSearcher struct {
+	name          string
+	searchResults []SearchResult
+	searchErr     error
+	downloadErr   error
+}
+
+func (m *mockSearcher) Search(ctx context.Context, opts *SearchOptions) ([]SearchResult, error) {
+	if m.searchErr != nil {
+		return nil, m.searchErr
+	}
+	return m.searchResults, nil
+}
+
+func (m *mockSearcher) Download(ctx context.Context, url string) (io.ReadCloser, error) {
+	if m.downloadErr != nil {
+		return nil, m.downloadErr
+	}
+	return io.NopCloser(strings.NewReader("mock image data")), nil
+}
+
+func (m *mockSearcher) GetAttribution(result *SearchResult) string {
+	return result.Attribution
+}
+
+func (m *mockSearcher) Name() string {
+	return m.name
+}
+
+func TestDefaultSearchOptions(t *testing.T) {
+	opts := DefaultSearchOptions("ябълка")
+	
+	if opts.Query != "ябълка" {
+		t.Errorf("Expected query 'ябълка', got '%s'", opts.Query)
+	}
+	
+	if opts.Language != "bg" {
+		t.Errorf("Expected language 'bg', got '%s'", opts.Language)
+	}
+	
+	if !opts.SafeSearch {
+		t.Error("Expected SafeSearch to be true")
+	}
+	
+	if opts.PerPage != 10 {
+		t.Errorf("Expected PerPage 10, got %d", opts.PerPage)
+	}
+	
+	if opts.Page != 1 {
+		t.Errorf("Expected Page 1, got %d", opts.Page)
+	}
+	
+	if opts.ImageType != "photo" {
+		t.Errorf("Expected ImageType 'photo', got '%s'", opts.ImageType)
+	}
+}
+
+func TestSearchError(t *testing.T) {
+	err := &SearchError{
+		Provider: "test",
+		Code:     "404",
+		Message:  "Not found",
+	}
+	
+	expected := "test: Not found"
+	if err.Error() != expected {
+		t.Errorf("Expected error '%s', got '%s'", expected, err.Error())
+	}
+}
+
+func TestRateLimitError(t *testing.T) {
+	err := &RateLimitError{
+		Provider:     "test",
+		RetryAfter:   60,
+		LimitPerHour: 100,
+	}
+	
+	expected := "test: rate limit exceeded"
+	if err.Error() != expected {
+		t.Errorf("Expected error '%s', got '%s'", expected, err.Error())
+	}
+}
+
+func TestMockSearcher(t *testing.T) {
+	mockResults := []SearchResult{
+		{
+			ID:          "1",
+			URL:         "https://example.com/image1.jpg",
+			Width:       800,
+			Height:      600,
+			Description: "Test image",
+			Source:      "mock",
+		},
+	}
+	
+	searcher := &mockSearcher{
+		name:          "mock",
+		searchResults: mockResults,
+	}
+	
+	ctx := context.Background()
+	opts := DefaultSearchOptions("test")
+	
+	results, err := searcher.Search(ctx, opts)
+	if err != nil {
+		t.Fatalf("Search() failed: %v", err)
+	}
+	
+	if len(results) != 1 {
+		t.Fatalf("Expected 1 result, got %d", len(results))
+	}
+	
+	if results[0].ID != "1" {
+		t.Errorf("Expected ID '1', got '%s'", results[0].ID)
+	}
+}
+
+func TestDownloadOptions(t *testing.T) {
+	opts := DefaultDownloadOptions()
+	
+	if opts.OutputDir != "./images" {
+		t.Errorf("Expected output dir './images', got '%s'", opts.OutputDir)
+	}
+	
+	if opts.OverwriteExisting {
+		t.Error("Expected OverwriteExisting to be false")
+	}
+	
+	if !opts.CreateDir {
+		t.Error("Expected CreateDir to be true")
+	}
+	
+	if opts.MaxSizeBytes != 10*1024*1024 {
+		t.Errorf("Expected MaxSizeBytes 10MB, got %d", opts.MaxSizeBytes)
+	}
+}
\ No newline at end of file
diff --git a/internal/image/translate.go b/internal/image/translate.go
new file mode 100644
index 0000000..03d5875
--- /dev/null
+++ b/internal/image/translate.go
@@ -0,0 +1,90 @@
+package image
+
+import "strings"
+
+// translateBulgarianQuery attempts to translate a Bulgarian query to English for better results
+// This is a simple implementation - in production you might use a translation API
+func translateBulgarianQuery(query string) string {
+	// Common Bulgarian words for flashcard creation
+	translations := map[string]string{
+		"ябълка": "apple",
+		"котка":  "cat",
+		"куче":   "dog",
+		"хляб":   "bread",
+		"вода":   "water",
+		"къща":   "house",
+		"дърво":  "tree",
+		"цвете":  "flower",
+		"книга":  "book",
+		"стол":   "chair",
+		"маса":   "table",
+		"прозорец": "window",
+		"врата":  "door",
+		"ръка":   "hand",
+		"око":    "eye",
+		"слънце": "sun",
+		"луна":   "moon",
+		"звезда": "star",
+		"море":   "sea",
+		"планина": "mountain",
+		"кола":   "car",
+		"автобус": "bus",
+		"влак":   "train",
+		"самолет": "airplane",
+		"училище": "school",
+		"учител": "teacher",
+		"ученик": "student",
+		"приятел": "friend",
+		"семейство": "family",
+		"майка":  "mother",
+		"баща":   "father",
+		"брат":   "brother",
+		"сестра": "sister",
+		"дете":   "child",
+		"мъж":    "man",
+		"жена":   "woman",
+		"момче":  "boy",
+		"момиче": "girl",
+		"храна":  "food",
+		"плод":   "fruit",
+		"зеленчук": "vegetable",
+		"мляко":  "milk",
+		"сирене": "cheese",
+		"месо":   "meat",
+		"риба":   "fish",
+		"пиле":   "chicken",
+		"яйце":   "egg",
+		"захар":  "sugar",
+		"сол":    "salt",
+		"кафе":   "coffee",
+		"чай":    "tea",
+		"вино":   "wine",
+		"бира":   "beer",
+		"сок":    "juice",
+		"град":   "city",
+		"село":   "village",
+		"улица":  "street",
+		"парк":   "park",
+		"магазин": "shop",
+		"ресторант": "restaurant",
+		"хотел":  "hotel",
+		"болница": "hospital",
+		"аптека": "pharmacy",
+		"банка":  "bank",
+		"пощa":   "post office",
+		"полиция": "police",
+		"пожарна": "fire station",
+		"летище": "airport",
+		"гара":   "train station",
+	}
+	
+	// Try exact match first
+	query = strings.ToLower(strings.TrimSpace(query))
+	if translated, ok := translations[query]; ok {
+		return translated
+	}
+	
+	// If no translation found, return original
+	// Pixabay might still return results for common words
+	return query
+}
\ No newline at end of file
diff --git a/internal/image/unsplash.go b/internal/image/unsplash.go
new file mode 100644
index 0000000..709ab17
--- /dev/null
+++ b/internal/image/unsplash.go
@@ -0,0 +1,263 @@
+package image
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"time"
+)
+
+const (
+	unsplashAPIURL = "https://api.unsplash.com"
+	unsplashTimeout = 30 * time.Second
+)
+
+// UnsplashClient implements ImageSearcher for Unsplash API
+type UnsplashClient struct {
+	accessKey   string
+	httpClient  *http.Client
+	rateLimit   *rateLimiter
+}
+
+// unsplashSearchResponse represents the search API response
+type unsplashSearchResponse struct {
+	Total      int             `json:"total"`
+	TotalPages int             `json:"total_pages"`
+	Results    []unsplashPhoto `json:"results"`
+}
+
+// unsplashPhoto represents a photo in the response
+type unsplashPhoto struct {
+	ID          string              `json:"id"`
+	CreatedAt   string              `json:"created_at"`
+	UpdatedAt   string              `json:"updated_at"`
+	Width       int                 `json:"width"`
+	Height      int                 `json:"height"`
+	Color       string              `json:"color"`
+	BlurHash    string              `json:"blur_hash"`
+	Description string              `json:"description"`
+	AltDesc     string              `json:"alt_description"`
+	URLs        unsplashPhotoURLs   `json:"urls"`
+	Links       unsplashPhotoLinks  `json:"links"`
+	User        unsplashUser        `json:"user"`
+}
+
+// unsplashPhotoURLs contains various size URLs
+type unsplashPhotoURLs struct {
+	Raw     string `json:"raw"`
+	Full    string `json:"full"`
+	Regular string `json:"regular"`
+	Small   string `json:"small"`
+	Thumb   string `json:"thumb"`
+}
+
+// unsplashPhotoLinks contains photo-related links
+type unsplashPhotoLinks struct {
+	Self     string `json:"self"`
+	HTML     string `json:"html"`
+	Download string `json:"download"`
+}
+
+// unsplashUser represents the photo author
+type unsplashUser struct {
+	ID       string `json:"id"`
+	Username string `json:"username"`
+	Name     string `json:"name"`
+}
+
+// NewUnsplashClient creates a new Unsplash API client
+func NewUnsplashClient(accessKey string) (*UnsplashClient, error) {
+	if accessKey == "" {
+		return nil, fmt.Errorf("Unsplash access key is required")
+	}
+	
+	return &UnsplashClient{
+		accessKey: accessKey,
+		httpClient: &http.Client{
+			Timeout: unsplashTimeout,
+		},
+		rateLimit: newRateLimiter(50), // 50 requests per hour
+	}, nil
+}
+
+// Search performs an image search on Unsplash
+func (u *UnsplashClient) Search(ctx context.Context, opts *SearchOptions) ([]SearchResult, error) {
+	// Apply rate limiting (50 per hour = ~0.83 per minute)
+	u.rateLimit.wait()
+	
+	// Build query parameters
+	params := url.Values{}
+	params.Set("query", opts.Query)
+	params.Set("per_page", fmt.Sprintf("%d", opts.PerPage))
+	params.Set("page", fmt.Sprintf("%d", opts.Page))
+	
+	if opts.Orientation != "all" && opts.Orientation != "" {
+		params.Set("orientation", mapOrientation(opts.Orientation))
+	}
+	
+	// Make request
+	reqURL := unsplashAPIURL + "/search/photos?" + params.Encode()
+	req, err := http.NewRequestWithContext(ctx, "GET", reqURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+	
+	// Add authorization header
+	req.Header.Set("Authorization", "Client-ID "+u.accessKey)
+	req.Header.Set("Accept-Version", "v1")
+	
+	resp, err := u.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+	
+	// Check status code
+	if resp.StatusCode == http.StatusTooManyRequests {
+		// Try to parse rate limit headers
+		retryAfter := 3600 // Default to 1 hour
+		if retryStr := resp.Header.Get("X-Ratelimit-Reset"); retryStr != "" {
+			// Parse Unix timestamp and calculate seconds until reset
+			// Implementation simplified for brevity
+			retryAfter = 3600
+		}
+		
+		return nil, &RateLimitError{
+			Provider:     "unsplash",
+			RetryAfter:   retryAfter,
+			LimitPerHour: 50,
+		}
+	}
+	
+	if resp.StatusCode == http.StatusUnauthorized {
+		return nil, &SearchError{
+			Provider: "unsplash",
+			Code:     "401",
+			Message:  "Invalid access key",
+		}
+	}
+	
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, &SearchError{
+			Provider: "unsplash",
+			Code:     fmt.Sprintf("%d", resp.StatusCode),
+			Message:  string(body),
+		}
+	}
+	
+	// Parse response
+	var searchResp unsplashSearchResponse
+	if err := json.NewDecoder(resp.Body).Decode(&searchResp); err != nil {
+		return nil, fmt.Errorf("failed to decode response: %w", err)
+	}
+	
+	// Convert to SearchResult
+	results := make([]SearchResult, 0, len(searchResp.Results))
+	for _, photo := range searchResp.Results {
+		description := photo.Description
+		if description == "" {
+			description = photo.AltDesc
+		}
+		
+		results = append(results, SearchResult{
+			ID:           photo.ID,
+			URL:          photo.URLs.Regular,
+			ThumbnailURL: photo.URLs.Thumb,
+			Width:        photo.Width,
+			Height:       photo.Height,
+			Description:  description,
+			Attribution:  u.formatAttribution(&photo),
+			Source:       "unsplash",
+		})
+	}
+	
+	// Trigger download tracking as per Unsplash guidelines
+	go u.trackDownloads(searchResp.Results)
+	
+	return results, nil
+}
+
+// Download downloads an image from the given URL
+func (u *UnsplashClient) Download(ctx context.Context, imageURL string) (io.ReadCloser, error) {
+	req, err := http.NewRequestWithContext(ctx, "GET", imageURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create download request: %w", err)
+	}
+	
+	resp, err := u.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("download failed: %w", err)
+	}
+	
+	if resp.StatusCode != http.StatusOK {
+		resp.Body.Close()
+		return nil, fmt.Errorf("download failed with status %d", resp.StatusCode)
+	}
+	
+	return resp.Body, nil
+}
+
+// GetAttribution returns the required attribution text for an image
+func (u *UnsplashClient) GetAttribution(result *SearchResult) string {
+	// Unsplash always requires attribution
+	return result.Attribution
+}
+
+// Name returns the name of the search provider
+func (u *UnsplashClient) Name() string {
+	return "unsplash"
+}
+
+// formatAttribution creates the proper attribution string as per Unsplash guidelines
+func (u *UnsplashClient) formatAttribution(photo *unsplashPhoto) string {
+	return fmt.Sprintf("Photo by %s on Unsplash", photo.User.Name)
+}
+
+// mapOrientation maps our orientation values to Unsplash API values
+func mapOrientation(orientation string) string {
+	switch orientation {
+	case "horizontal":
+		return "landscape"
+	case "vertical":
+		return "portrait"
+	default:
+		return ""
+	}
+}
+
+// trackDownloads triggers download events as required by Unsplash API guidelines
+func (u *UnsplashClient) trackDownloads(photos []unsplashPhoto) {
+	// Unsplash requires triggering their download endpoint when images are used
+	// This is done asynchronously to not block the search
+	for _, photo := range photos {
+		go func(downloadURL string) {
+			req, _ := http.NewRequest("GET", downloadURL, nil)
+			req.Header.Set("Authorization", "Client-ID "+u.accessKey)
+			u.httpClient.Do(req)
+		}(photo.Links.Download)
+	}
+}
+
+// SearchWithTranslation performs a search with automatic translation
+// Unsplash has better international support, so we'll try both queries
+func (u *UnsplashClient) SearchWithTranslation(ctx context.Context, opts *SearchOptions) ([]SearchResult, error) {
+	// First try with original Bulgarian query
+	results, err := u.Search(ctx, opts)
+	if err == nil && len(results) > 0 {
+		return results, nil
+	}
+	
+	// If no results, try with translated query
+	translatedQuery := translateBulgarianQuery(opts.Query)
+	if translatedQuery != opts.Query {
+		translatedOpts := *opts
+		translatedOpts.Query = translatedQuery
+		return u.Search(ctx, &translatedOpts)
+	}
+	
+	return results, err
+}
\ No newline at end of file
diff --git a/internal/version.go b/internal/version.go
new file mode 100644
index 0000000..93a42a8
--- /dev/null
+++ b/internal/version.go
@@ -0,0 +1,3 @@
+package internal
+
+const Version = "0.0.0"