Feature/voice preview

[sharadcodes]

Description

This PR implements a premium Voice Preview feature in Awaaz, allowing users to listen to any selected voice (default or custom) before starting a full audiobook generation job. Previews are accessible from both the audiobook Generation Form and the Settings Modal.

Key Additions & Improvements

• Self-Cleaning Backend API: Added a POST /api/v1/backends/{name}/preview endpoint. It synthesizes a short WAV snippet, converts it to MP3 using FFmpeg, and streams it back. Temporary audio files are cleaned up immediately post-stream using FastAPI BackgroundTasks to avoid disk leaks.
• Custom Preview Text: Added an optional custom text field in the Generation Form so users can type custom sentences (up to 500 characters) to test specific word pronunciations.
• Reusable Audio Hook: Built a custom useVoicePreview hook in the frontend to manage audio playback, load state transitions, and ensure resource cleanup (object URL revocation) when components unmount.
• Polished UX: Added play/stop/loading buttons next to voice selectors, styled inline error states, and added a keyframe spin animation for the loader.
• Form Grid Baseline Fix: Defined .field-span { grid-column: span 2; } in styles.css to fix vertical layout misalignment in the form fields.

---

Files Changed

Backend

• src/awaaz/api.py — Added /backends/{name}/preview endpoint and PreviewRequest validation.
• tests/test_api_preview.py — Created unit tests for preview successes, invalid engines, text length limits, and adapter errors.
• tests/test_api_contract.py — Verified preview route is successfully generated in OpenAPI schema.

Frontend

• frontend/src/api/client.ts — Added previewVoice fetch client wrapper.
• frontend/src/hooks/useVoicePreview.ts — Created a custom playback hook.
• frontend/src/components/VoiceSelector.tsx — Styled selector dropdown row to include loading/playing buttons.
• frontend/src/components/GenerationForm.tsx — Wired hook, added custom preview text inputs, and handled state overrides.
• frontend/src/components/SettingsModal.tsx — Added voice preview support for default voice settings.
• frontend/src/styles.css — Added layout styling, play/stop button designs, and animation keyframes.
• frontend/src/__tests__/api.test.ts — Added fetch API mocks to verify the preview client function.

---

Verification & Testing

Automated Tests

• Backend Tests: Verified all tests pass via uv run pytest (43 passed).
• Frontend Tests: Verified all tests pass via npm run test (5 passed).
• Linting & Formatting: Checked Ruff, MyPy type checks, ESLint, and Prettier checks. All checks passed with 100% clean formatting and typing.