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/utils/audio.py

@@ -2,11 +2,15 @@
 
 import hashlib
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import ffmpeg  # type: ignore[import-untyped]
 
 from app.core.logging import get_logger
 
+if TYPE_CHECKING:
+    from app.models.sound import Sound
+
 logger = get_logger(__name__)
 
 
@@ -33,3 +37,30 @@ def get_audio_duration(file_path: Path) -> int:
     except Exception as e:
         logger.warning("Failed to get duration for %s: %s", file_path, e)
         return 0
+
+
+def get_sound_file_path(sound: "Sound") -> Path:
+    """Get the file path for a sound based on its type and normalization status.
+
+    Args:
+        sound: The Sound object to get the path for
+
+    Returns:
+        Path: The full path to the sound file
+
+    """
+    # Determine the correct subdirectory based on sound type
+    if sound.type.upper() == "EXT":
+        subdir = "extracted"
+    elif sound.type.upper() == "SDB":
+        subdir = "soundboard"
+    elif sound.type.upper() == "TTS":
+        subdir = "text_to_speech"
+    else:
+        # Fallback to lowercase type
+        subdir = sound.type.lower()
+
+    # Use normalized file if available, otherwise original
+    if sound.is_normalized and sound.normalized_filename:
+        return Path("sounds/normalized") / subdir / sound.normalized_filename
+    return Path("sounds/originals") / subdir / sound.filename