feat: Add voice preview feature to podcast generation

[google-labs-jules]

This change introduces a new voice preview feature to the podcast generation modal, allowing users to listen to a sample of each voice before making a selection.

Key changes:

• Replaced the voice selection dropdowns with a new interactive VoiceSelector component.
• Added a play/pause button next to each voice option to trigger an audio preview.
• Implemented a new backend endpoint at /api/podcasts/voice-preview/{voice_id} to generate and serve the voice previews.

Note:

• The unit tests are currently failing due to an unresolved issue with an environment variable.
• Frontend verification was skipped due to a Docker permission error that prevented the development server from starting.

---

PR created automatically by Jules for task 16486211777656576908

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

---

For security, I will only act on instructions from the user who triggered this task.

[github-actions]

🚀 Development Environment Options

This repository supports Dev Containers for a consistent development environment.

Option 1: GitHub Codespaces (Recommended)

Create a cloud-based development environment:

1. Click the green Code button above
2. Select the Codespaces tab
3. Click Create codespace on feature/issue-300-voice-preview
4. Wait 2-3 minutes for environment setup
5. Start coding with all tools pre-configured!

Option 2: VS Code Dev Containers (Local)

Use Dev Containers on your local machine:

1. Install Docker Desktop
2. Install VS Code
3. Install the Dev Containers extension
4. Clone this PR branch locally
5. Open in VS Code and click "Reopen in Container" when prompted

Option 3: Traditional Local Setup

Set up the development environment manually:

# Clone the repository
git clone https://github.com/manavgup/rag_modulo.git
cd rag_modulo
git checkout feature/issue-300-voice-preview

# Initialize development environment
make dev-init
make dev-build
make dev-up
make dev-validate

Available Commands

Once in your development environment:

make help           # Show all available commands
make dev-validate   # Validate environment setup
make test-atomic    # Run atomic tests
make test-unit      # Run unit tests
make lint          # Run linting

Services Available

When running make dev-up:

• Backend API: http://localhost:8000
• Frontend: http://localhost:3000
• MLflow: http://localhost:5001

---

This automated message helps reviewers quickly set up the development environment.

[claude]

Code Review: Voice Preview Feature

Summary

This PR adds a voice preview feature to the podcast generation modal. Overall, the implementation is functional and well-structured, but there are several areas for improvement regarding code quality, error handling, and testing.

---

🟢 Strengths

1. Good Component Separation: The new VoiceSelector component properly encapsulates the voice selection UI logic.
2. Clean API Design: The /voice-preview/{voice_id} endpoint is simple and follows RESTful conventions.
3. User Experience: The play/pause toggle and visual feedback improve the user experience.
4. Proper Resource Cleanup: The useEffect cleanup in PodcastGenerationModal.tsx prevents memory leaks.

---

🔴 Critical Issues

1. Missing Import in Backend (podcast_service.py:586-621)

async def generate_voice_preview(self, voice_id: str) -> bytes:
    ...
    raise HTTPException(...)

Problem: HTTPException is used but not imported.

Fix: Add import at the top of the file:

from fastapi import HTTPException

2. Missing Tests

The PR description mentions failing unit tests, but no tests were added for the new functionality. According to CLAUDE.md, new features should have both unit and integration tests.

Required Tests:

• Unit test for PodcastService.generate_voice_preview()
• API integration test for /voice-preview/{voice_id} endpoint
• Frontend component tests for VoiceSelector

Suggested test file: backend/tests/unit/test_podcast_service_unit.py

3. No Input Validation (podcast_router.py:240-255)

The voice_id parameter accepts any string without validation.

Concerns:

• Path traversal attempts (e.g., ../../secret)
• Invalid voice IDs causing unclear errors
• No authentication check (any user can preview any voice)

Recommendation: Add validation:

from rag_solution.schemas.podcast_schema import VOICE_OPTIONS

@router.get("/voice-preview/{voice_id}")
async def get_voice_preview(
    voice_id: str,
    podcast_service: Annotated[PodcastService, Depends(get_podcast_service)],
) -> StreamingResponse:
    # Validate voice_id exists
    valid_voice_ids = [v.id for v in VOICE_OPTIONS]
    if voice_id not in valid_voice_ids:
        raise HTTPException(
            status_code=400,
            detail=f"Invalid voice_id. Must be one of: {valid_voice_ids}"
        )
    ...

---

🟡 Code Quality Issues

4. Hardcoded Preview Text (podcast_service.py:606)

preview_text = "Hello, you are listening to a preview of this voice."

Issue: Hardcoded strings should be constants or configurable.

Recommendation:

# At class level
VOICE_PREVIEW_TEXT = "Hello, you are listening to a preview of this voice."

# In method
preview_text = self.VOICE_PREVIEW_TEXT

5. Inconsistent Error Handling (PodcastGenerationModal.tsx:80-82)

console.error('Error playing voice preview:', error);
addNotification('error', 'Preview Failed', 'Could not load voice preview.');

Issue: Error details are logged but not shown to the user. The notification message is generic.

Recommendation: Provide more context:

const errorMessage = error instanceof Error ? error.message : 'Unknown error';
addNotification('error', 'Preview Failed', `Could not load voice preview: ${errorMessage}`);

6. Missing Type Safety (apiClient.ts:888)

async getVoicePreview(voiceId: string): Promise<Blob>

Issue: No validation that voiceId is a valid voice identifier.

Recommendation: Define a voice ID type:

type VoiceId = 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer';

async getVoicePreview(voiceId: VoiceId): Promise<Blob>

7. Unused Import (podcast_router.py:21)

import io

Issue: The import is used in line 254 (io.BytesIO), so this is fine. However, consider organizing imports per PEP 8 (standard library, third-party, local).

Current order:

from fastapi import ...
...
import io  # Should come first

---

⚡ Performance Considerations

8. No Caching for Voice Previews

Each preview request generates audio on-the-fly. For the same preview text, this is wasteful.

Recommendation: Implement caching:

from functools import lru_cache

@lru_cache(maxsize=10)  # Cache up to 10 voice previews
async def _generate_cached_preview(voice_id: str) -> bytes:
    ...

Or use Redis/file-based caching for better persistence.

9. Memory Leak Risk in Frontend (VoiceSelector.tsx)

If a user rapidly clicks play/pause on different voices, multiple Audio objects could be created without proper cleanup.

Current code (PodcastGenerationModal.tsx:68-70):

if (audioRef.current) {
    audioRef.current.pause();
}

Issue: The old Audio object isn't properly disposed; only paused.

Fix:

if (audioRef.current) {
    audioRef.current.pause();
    audioRef.current.src = '';  // Release resources
    audioRef.current = null;
}

---

🔒 Security Concerns

10. No Rate Limiting

The endpoint has no rate limiting, which could allow abuse (e.g., DOS attacks by repeatedly requesting previews).

Recommendation: Add rate limiting middleware or decorator:

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)

@router.get("/voice-preview/{voice_id}")
@limiter.limit("10/minute")  # 10 requests per minute
async def get_voice_preview(...):
    ...

11. Missing Authentication

The endpoint doesn't require authentication. While voice previews aren't sensitive, consistency with other endpoints is important.

Recommendation: Add user authentication dependency if needed:

from rag_solution.router.auth_router import get_current_user

@router.get("/voice-preview/{voice_id}")
async def get_voice_preview(
    voice_id: str,
    current_user: User = Depends(get_current_user),  # Add if needed
    ...
):

---

📋 Testing Requirements

Based on CLAUDE.md guidelines, please add:

1. Unit Tests (backend/tests/unit/test_podcast_service_unit.py):

@pytest.mark.unit
async def test_generate_voice_preview_success():
    """Test successful voice preview generation."""
    # Test with valid voice_id
    # Assert audio_bytes returned
    # Assert audio provider called correctly

@pytest.mark.unit
async def test_generate_voice_preview_invalid_voice():
    """Test voice preview with invalid voice_id."""
    # Test with invalid voice_id
    # Assert HTTPException raised

2. Integration Tests (backend/tests/integration/test_podcast_api.py):

@pytest.mark.integration
async def test_voice_preview_endpoint():
    """Test /voice-preview endpoint returns audio."""
    # Test GET /api/podcasts/voice-preview/{voice_id}
    # Assert 200 status
    # Assert content-type is audio/mpeg
    # Assert response body is valid audio data

3. Frontend Tests: Add tests for VoiceSelector component.

---

📝 Documentation Needs

1. API Documentation: Update API docs to include the new endpoint.
2. Docstring Enhancement: The generate_voice_preview docstring should mention:
   • Supported voice IDs
   • Audio format (MP3)
   • Expected response size
   • Error conditions

---

✅ Action Items

Before Merge:

• Fix missing HTTPException import
• Add input validation for voice_id
• Add unit tests for generate_voice_preview()
• Add integration tests for /voice-preview endpoint
• Fix memory cleanup in audio player
• Resolve the environment variable issue mentioned in PR description

Nice to Have:

• Implement caching for voice previews
• Add rate limiting
• Make preview text configurable
• Add authentication if required by project policy
• Update API documentation

---

🎯 Conclusion

The feature implementation is solid from a UX perspective, but needs attention to error handling, testing, and security before merging. The critical issues (missing import, no validation, no tests) should be addressed immediately.

Estimated effort to address critical issues: 2-3 hours

Let me know if you need help implementing any of these suggestions!