feat(media): use VLC :start-volume for initial audio; document volume bug

Passes :start-volume media option to VLC on play. Removes polling/delay
volume hacks. Documents 9.7 volume bug in testing plan — VLC ignores
initial volume on macOS, needs further investigation.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/service/media/GlobalMediaPlayer.kt

@@ -153,9 +153,8 @@ object GlobalMediaPlayer {
                 player.events().addMediaPlayerEventListener(seekListener)
             }
 
-            player.media().play(url)
+            val vol = _videoState.value.volume
-            // Set volume after play — VLC resets volume on new media
+            player.media().play(url, ":start-volume=$vol")
-            player.audio().setVolume(_videoState.value.volume)
             startVideoPolling()
         }
     }
@@ -192,9 +191,8 @@ object GlobalMediaPlayer {
                 audioPlayer = player
             }
 
-            player.media().play(url)
+            val vol = _audioState.value.volume
-            // Set volume after play — VLC resets volume on new media
+            player.media().play(url, ":start-volume=$vol")
-            player.audio().setVolume(_audioState.value.volume)
             startAudioPolling()
         }
     }
@@ -364,16 +362,6 @@ object GlobalMediaPlayer {
                             isBuffering = false,
                             duration = mediaPlayer.status().length(),
                         )
-                    // Enforce volume after a short delay — VLC's audio output
-                    // may not be ready immediately when the playing event fires
-                    scope.launch {
-                        delay(100)
-                        try {
-                            mediaPlayer.audio().setVolume(state.volume)
-                            mediaPlayer.audio().isMute = state.isMuted
-                        } catch (_: Exception) {
-                        }
-                    }
                 }
 
                 override fun paused(mediaPlayer: MediaPlayer) {
@@ -424,23 +412,12 @@ object GlobalMediaPlayer {
         player.events().addMediaPlayerEventListener(
             object : MediaPlayerEventAdapter() {
                 override fun playing(mediaPlayer: MediaPlayer) {
-                    val state = _audioState.value
                     _audioState.value =
-                        state.copy(
+                        _audioState.value.copy(
                             isPlaying = true,
                             isBuffering = false,
                             duration = mediaPlayer.status().length(),
                         )
-                    // Enforce volume after a short delay — VLC's audio output
-                    // may not be ready immediately when the playing event fires
-                    scope.launch {
-                        delay(100)
-                        try {
-                            mediaPlayer.audio().setVolume(state.volume)
-                            mediaPlayer.audio().isMute = state.isMuted
-                        } catch (_: Exception) {
-                        }
-                    }
                 }
 
                 override fun paused(mediaPlayer: MediaPlayer) {

docs/plans/2026-03-16-desktop-media-manual-testing-plan.md

@@ -138,12 +138,13 @@ Branch has 13 commits implementing Phases 0-9 of desktop media: image display, u
 
 | # | Test | Steps | Expected | Status |
 |---|------|-------|----------|--------|
-| 9.1 | Inline audio | Note with MP3 URL | Audio player renders inline | |
+| 9.1 | Inline audio | Note with MP3 URL | Audio player renders inline | ✅ PASS |
-| 9.2 | Play/pause | Click play | Audio plays; click again pauses | |
+| 9.2 | Play/pause | Click play | Audio plays; click again pauses | ✅ PASS |
-| 9.3 | Seek | Drag seek bar | Playback jumps to position | |
+| 9.3 | Seek | Drag seek bar | Playback jumps to position | ✅ PASS |
-| 9.4 | Time display | Play audio file | Shows current/total time | |
+| 9.4 | Time display | Play audio file | Shows current/total time | ✅ PASS |
-| 9.5 | Multiple formats | Notes with OGG, WAV, FLAC, AAC, OPUS, M4A | All play (where VLC supports) | |
+| 9.5 | Multiple formats | Notes with OGG, WAV, FLAC, AAC, OPUS, M4A | All play (where VLC supports) | ⬜ TODO |
-| 9.6 | Audio pool | Scroll past 6+ audio notes | Max 5 audio players; earlier ones release | |
+| 9.6 | Audio pool | Scroll past 6+ audio notes | Max 5 audio players; earlier ones release | N/A — GlobalMediaPlayer uses single shared player now |
+| 9.7 | Initial volume | Play audio without touching volume slider | Audio audible at 100% on first play | 🐛 BUG — VLC starts silent; moving volume slider fixes it. Tried `:start-volume`, `setVolume` in playing callback, delayed retries — none work. Needs investigation into VLCJ audio output init timing on macOS. |
 
 ---