feat: Add VLC player API endpoints and associated tests

- Implemented VLC player API endpoints for playing and stopping sounds.
- Added tests for successful playback, error handling, and authentication scenarios.
- Created utility function to get sound file paths based on sound properties.
- Refactored player service to utilize shared sound path utility.
- Enhanced test coverage for sound file path utility with various sound types.
- Introduced tests for VLC player service, including subprocess handling and play count tracking.

app/api/v1/sounds.py

@@ -8,10 +8,12 @@ from sqlmodel.ext.asyncio.session import AsyncSession
 from app.core.database import get_db
 from app.core.dependencies import get_current_active_user_flexible
 from app.models.user import User
+from app.repositories.sound import SoundRepository
 from app.services.extraction import ExtractionInfo, ExtractionService
 from app.services.extraction_processor import extraction_processor
 from app.services.sound_normalizer import NormalizationResults, SoundNormalizerService
 from app.services.sound_scanner import ScanResults, SoundScannerService
+from app.services.vlc_player import get_vlc_player_service, VLCPlayerService
 
 router = APIRouter(prefix="/sounds", tags=["sounds"])
 
@@ -37,6 +39,19 @@ async def get_extraction_service(
     return ExtractionService(session)
 
 
+def get_vlc_player() -> VLCPlayerService:
+    """Get the VLC player service."""
+    from app.core.database import get_session_factory
+    return get_vlc_player_service(get_session_factory())
+
+
+async def get_sound_repository(
+    session: Annotated[AsyncSession, Depends(get_db)],
+) -> SoundRepository:
+    """Get the sound repository."""
+    return SoundRepository(session)
+
+
 # SCAN
 @router.post("/scan")
 async def scan_sounds(
@@ -349,3 +364,64 @@ async def get_user_extractions(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail=f"Failed to get extractions: {e!s}",
         ) from e
+
+
+# VLC PLAYER
+@router.post("/vlc/play/{sound_id}")
+async def play_sound_with_vlc(
+    sound_id: int,
+    current_user: Annotated[User, Depends(get_current_active_user_flexible)],
+    vlc_player: Annotated[VLCPlayerService, Depends(get_vlc_player)],
+    sound_repo: Annotated[SoundRepository, Depends(get_sound_repository)],
+) -> dict[str, str | int | bool]:
+    """Play a sound using VLC subprocess."""
+    try:
+        # Get the sound
+        sound = await sound_repo.get_by_id(sound_id)
+        if not sound:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Sound with ID {sound_id} not found",
+            )
+
+        # Play the sound using VLC
+        success = await vlc_player.play_sound(sound)
+        
+        if not success:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Failed to launch VLC for sound playback",
+            )
+
+        return {
+            "message": f"Sound '{sound.name}' is now playing via VLC",
+            "sound_id": sound_id,
+            "sound_name": sound.name,
+            "success": True,
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to play sound: {e!s}",
+        ) from e
+
+
+
+@router.post("/vlc/stop-all")
+async def stop_all_vlc_instances(
+    current_user: Annotated[User, Depends(get_current_active_user_flexible)],
+    vlc_player: Annotated[VLCPlayerService, Depends(get_vlc_player)],
+) -> dict:
+    """Stop all running VLC instances."""
+    try:
+        result = await vlc_player.stop_all_vlc_instances()
+        return result
+
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to stop VLC instances: {e!s}",
+        ) from e