feat: Add subtitle generation and editing system

[GauravOP-03]

📝 Description

This PR introduces a comprehensive subtitle generation and editing system that allows users to upload videos, generate AI-powered subtitles using Google Gemini AI, edit subtitles in real-time, and download videos with burned-in subtitles. The implementation includes both backend API endpoints (NestJS) and a complete frontend interface (Next.js) with advanced subtitle editing capabilities.

Key Features:

• Video upload (max 200MB, 10 minutes duration)
• AI-powered subtitle generation with language detection
• Subtitle translation support
• Real-time subtitle editing with video synchronization
• Subtitle import/export (SRT format)
• Video download with burned-in subtitles
• Credit system integration
• Permission-based access control

🎯 Type of Change

• ✨ New feature (non-breaking change which adds functionality)
• ♻️ Refactoring (API client migrated from fetch to axios)

🔗 Related Issue

🧪 Testing

• I have tested my changes locally
• I have added tests for my changes
• All existing tests pass
• I have tested on different browsers/devices (if applicable)

📋 Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have checked my code and corrected any misspellings
• I have read the Contributing Guide

📸 Screenshots (if applicable)

🔧 Technical Details

Backend Implementation

New Module: Subtitle Module (apps/api/src/subtitle/)

• SubtitleController: REST API endpoints for subtitle operations

  • POST /subtitle - Create subtitle generation job
  • GET /subtitle - Get user's subtitle jobs (latest 10)
  • GET /subtitle/:id - Get specific subtitle
  • POST /subtitle/upload - Upload video file
  • PATCH /subtitle/:id - Update subtitle data
  • DELETE /subtitle/:id - Delete subtitle and video
  • POST /subtitle/burn - Generate video with burned subtitles

• SubtitleService: Core business logic

  • Google Gemini AI integration for subtitle generation
  • Language detection and translation support
  • FFmpeg integration for video processing
  • Supabase storage integration for video files
  • Credit system integration
  • Permission validation

• DTOs: Data transfer objects for API requests

  • CreateSubtitleDto, UpdateSubtitleDto, UploadVideoDto, BurnSubtitleDto

• Utilities: Helper functions for video processing

  • Video URL handling and buffer conversion
  • SRT format conversion
  • FFmpeg configuration

Frontend Implementation

New Pages:

• /dashboard/subtitles - Main listing page with uploader and history
• /dashboard/subtitles/[id] - Subtitle editor page with video player

New Components:

• SubtitleUploader - Video file upload interface
• SubtitleHistory - List of subtitle jobs
• VideoPlayer - Video player with subtitle overlay
• SubtitleEditorPanel - Full-featured subtitle editor
• GenerateSubtitlesForm - Language selection and generation form
• SubtitleHeader, SubtitleItem, SubtitleList, SubtitleEmptyState
• Loading skeletons for better UX

New Hooks:

• useSubtitleGeneration - Manages subtitle generation workflow
• useSubtitleData - Handles subtitle data fetching and state
• useSubtitleEditor - Manages subtitle editing operations
• useSubtitleFileOperations - Handles save, download, upload operations
• useVideoPlayer - Manages video player state and synchronization
• useDebounce - Generic debounce hook for performance

New Utilities:

• SRT parsing and conversion
• Time format conversion (HH:MM:SS.mmm ↔ seconds)
• VTT format conversion for video player
• JSON to SRT conversion

Refactored:

• api-client.ts: Migrated from native fetch to axios for better file upload support, interceptors, and error handling

New Dependencies:

• Backend: @google/genai, fluent-ffmpeg, @ffmpeg-installer/ffmpeg, @ffprobe-installer/ffprobe, multer
• Frontend: No new dependencies (uses existing axios, motion, sonner)

Technical Decisions

1. Axios over Fetch: Better file upload support, interceptors, progress tracking, and error handling
2. Google Gemini AI: Multimodal capabilities for accurate subtitle generation
3. FFmpeg: Industry standard for video processing and subtitle burning
4. Component Composition: Separated concerns with dedicated hooks and components
5. Optimistic UI Updates: Better perceived performance for delete operations
6. Debounced Updates: Prevents excessive re-renders for VTT generation
7. Type Safety: Shared types between frontend and backend via validation package

🚀 Deployment Notes

Required Environment Variables:

• GOOGLE_GENERATIVE_AI_API_KEY - Google Generative AI API key

Database Schema Requirements:

• subtitle_jobs table with columns: id, user_id, video_path, video_url, subtitles_json, status, language, detected_language, target_language, duration, error_message, created_at, updated_at
• User profile table should have: credits, ai_trained, youtube_connected columns

Storage Requirements:

• Supabase storage bucket: video_subtitles for video file storage

Server Requirements:

• FFmpeg must be available (handled via @ffmpeg-installer/ffmpeg)
• Node.js environment with file system access for temporary file processing

📚 Documentation Updates

• PR description includes comprehensive documentation
• README.md updated (if needed)
• API documentation updated (if needed)
• Component documentation updated (if needed)

🔍 Review Notes

Areas to focus on during review:

1. Subtitle Service (subtitle.service.ts): Core logic for AI generation and video processing - review error handling and credit management
2. API Client Refactor (api-client.ts): Migration from fetch to axios - ensure backward compatibility
3. Subtitle Editor: Real-time synchronization and editing logic
4. File Upload: Video validation and upload flow
5. Error Handling: Comprehensive error handling across all operations

Potential Questions:

• Are file size and duration limits appropriate (200MB, 10 minutes)?
• Is credit deduction timing correct (after successful generation)?
• Are temporary files properly cleaned up in all error scenarios?

📊 Performance Impact

• Performance improvement

Performance Improvements:

• Optimistic UI updates for instant feedback
• Debounced subtitle updates prevent excessive re-renders
• Efficient video player synchronization
• Proper cleanup of temporary files and blob URLs

Performance Considerations:

• Video processing (burning subtitles) is CPU-intensive and runs server-side
• Large video files (up to 200MB) require adequate server resources
• Subtitle generation via AI API may take time depending on video length

🔒 Security Considerations

• Security improvement

Security Measures:

• All endpoints protected by SupabaseAuthGuard
• User permission validation (AI trained or YouTube connected)
• Credit system prevents abuse
• File upload validation (size, type, duration limits)
• User-specific data isolation (all queries filtered by user_id)
• Temporary file cleanup to prevent disk space issues

Security Notes:

• Video files stored in user-specific paths in Supabase storage
• Authentication tokens handled securely via axios interceptors
• File validation prevents malicious file uploads

🎉 Additional Notes

Future Improvements:

• Add Zod validation for backend DTOs to improve runtime validation and type safety
• Add unit tests for subtitle service and utilities
• Add integration tests for subtitle generation flow
• Consider adding subtitle style customization
• Consider adding batch subtitle generation for multiple videos

Migration Notes:

• This is a new feature, no breaking changes to existing functionality
• Existing subtitle-related code (if any) should be reviewed for conflicts
• Database migrations needed for subtitle_jobs table (if not already created)

---

🔗 Related Issue

Closes #77

[vercel]

@GauravOP-03 is attempting to deploy a commit to the afrin127329's projects Team on Vercel.

A member of the Team first needs to authorize it.