refactor: Improve code readability by formatting query parameters in user endpoints and enhancing error handling in sound playback

app/api/v1/sounds.py

@@ -33,6 +33,68 @@ def get_favorite_service() -> FavoriteService:
     return FavoriteService(get_session_factory())
 
 
+async def play_sound_internal(
+    sound_id: int, user_id: str,
+) -> dict[str, str | int | bool]:
+    """Play sound with VLC internally (used by HTTP and WebSocket endpoints)."""
+    session_factory = get_session_factory()
+
+    # Create services
+    vlc_player = get_vlc_player()
+    credit_service = get_credit_service()
+
+    async with session_factory() as session:
+        sound_repo = SoundRepository(session)
+
+        # 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",
+            )
+
+        # Check and validate credits before playing
+        try:
+            await credit_service.validate_and_reserve_credits(
+                int(user_id),
+                CreditActionType.VLC_PLAY_SOUND,
+            )
+        except InsufficientCreditsError as e:
+            raise HTTPException(
+                status_code=status.HTTP_402_PAYMENT_REQUIRED,
+                detail=(
+                    f"Insufficient credits: {e.required} required, "
+                    f"{e.available} available"
+                ),
+            ) from e
+
+        # Play the sound using VLC
+        success = await vlc_player.play_sound(sound)
+
+        # Deduct credits based on success
+        await credit_service.deduct_credits(
+            int(user_id),
+            CreditActionType.VLC_PLAY_SOUND,
+            success=success,
+            metadata={"sound_id": sound_id, "sound_name": sound.name},
+        )
+
+        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,
+            "credits_deducted": 1,
+        }
+
+
 async def get_sound_repository(
     session: Annotated[AsyncSession, Depends(get_db)],
 ) -> SoundRepository:
@@ -91,11 +153,14 @@ async def get_sounds(  # noqa: PLR0913
         sound_responses = []
         for sound in sounds:
             is_favorited = await favorite_service.is_sound_favorited(
-                current_user.id, sound.id,
+                current_user.id,
+                sound.id,
             )
             favorite_count = await favorite_service.get_sound_favorite_count(sound.id)
             sound_response = SoundResponse.from_sound(
-                sound, is_favorited, favorite_count,
+                sound,
+                is_favorited,
+                favorite_count,
             )
             sound_responses.append(sound_response)
 
@@ -113,52 +178,10 @@ async def get_sounds(  # noqa: PLR0913
 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)],
-    credit_service: Annotated[CreditService, Depends(get_credit_service)],
 ) -> dict[str, str | int | bool]:
     """Play a sound using VLC subprocess (requires 1 credit)."""
     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",
-            )
-
-        # Check and validate credits before playing
-        try:
-            await credit_service.validate_and_reserve_credits(
-                current_user.id,
-                CreditActionType.VLC_PLAY_SOUND,
-            )
-        except InsufficientCreditsError as e:
-            raise HTTPException(
-                status_code=status.HTTP_402_PAYMENT_REQUIRED,
-                detail=(
-                    f"Insufficient credits: {e.required} required, "
-                    f"{e.available} available"
-                ),
-            ) from e
-
-        # Play the sound using VLC
-        success = await vlc_player.play_sound(sound)
-
-        # Deduct credits based on success
-        await credit_service.deduct_credits(
-            current_user.id,
-            CreditActionType.VLC_PLAY_SOUND,
-            success=success,
-            metadata={"sound_id": sound_id, "sound_name": sound.name},
-        )
-
-        if not success:
-            raise HTTPException(
-                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-                detail="Failed to launch VLC for sound playback",
-            )
-
+        return await play_sound_internal(sound_id, str(current_user.id))
     except HTTPException:
         raise
     except Exception as e:
@@ -166,14 +189,6 @@ async def play_sound_with_vlc(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail=f"Failed to play sound: {e!s}",
         ) from e
-    else:
-        return {
-            "message": f"Sound '{sound.name}' is now playing via VLC",
-            "sound_id": sound_id,
-            "sound_name": sound.name,
-            "success": True,
-            "credits_deducted": 1,
-        }
 
 
 @router.post("/stop")