From bd1a6c44ee9da6c385fe0ee0401ca44913820973 Mon Sep 17 00:00:00 2001
From: Damontecres <damontecres@gmail.com>
Date: Tue, 11 Aug 2026 13:33:49 -0400
Subject: [PATCH] Add shuffle parameter to playback intent (#1813)

## Description
Adds an optional boolean parameter `shuffle` that is read for the
playback intent. When true, it will cause the resulting media to be
shuffled if applicable.

Something can be shuffled if the `itemId` is a grouping on media such as
a playlist, series, season, or even library.

### Related issues
Depends on #1756

### Testing
Emulator with the documented command

## Screenshots
N/A

## AI or LLM usage
None
---
 Intents.md                                        | 15 ++++++++++++---
 .../wholphin/services/IntentService.kt            |  2 ++
 .../damontecres/wholphin/ui/nav/Destination.kt    |  1 +
 .../wholphin/ui/playback/PlaybackViewModel.kt     |  7 +++++++
 4 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/Intents.md b/Intents.md
index a083ae7a..02511787 100644
--- a/Intents.md
+++ b/Intents.md
@@ -1,8 +1,5 @@
 # Intents
 
-> [!WARNING]
-> This feature is only available in the develop builds until the next release!
-
 > [!IMPORTANT]
 > This feature is experimental and the exact behaviors and/or parameters may change at any time
 
@@ -93,6 +90,7 @@ Shorthand action: `play`
 Parameters:
 - `itemId` - Required, the UUID of the media item
 - `position` - Optional, the start position for playback in milliseconds
+- `shuffle` - Optional, whether to shuffle the resulting items
 
 ### Examples
 
@@ -120,6 +118,17 @@ adb shell am start \
 adb shell am start -d 'wholphin://play?itemId=5cf8f8e7-2a5f-4aa9-8c12-ddf63d42ee6d\&position=270000'
 ```
 
+Shuffle a series (`itemId` is the Series ID):
+```bash
+adb shell am start \
+  -a com.github.damontecres.wholphin.PLAYBACK \
+  -n 'com.github.damontecres.wholphin/.MainActivity' \
+  --es itemId "5cf8f8e7-2a5f-4aa9-8c12-ddf63d42ee6d" \
+  --ez shuffle true
+
+adb shell am start -d 'wholphin://play?itemId=5cf8f8e7-2a5f-4aa9-8c12-ddf63d42ee6d\&shuffle=true'
+```
+
 ## More examples
 
 ### Switch user
diff --git a/app/src/main/java/com/github/damontecres/wholphin/services/IntentService.kt b/app/src/main/java/com/github/damontecres/wholphin/services/IntentService.kt
index da59b98d..95343b47 100644
--- a/app/src/main/java/com/github/damontecres/wholphin/services/IntentService.kt
+++ b/app/src/main/java/com/github/damontecres/wholphin/services/IntentService.kt
@@ -103,11 +103,13 @@ class IntentService
 
                     "com.github.damontecres.wholphin.PLAYBACK", "play" -> {
                         val position = intent.getLongParam("position")?.coerceAtLeast(0)
+                        val shuffle = intent.getBooleanExtra("shuffle", false)
 
                         val playbackDestination =
                             Destination.Playback(
                                 itemId = itemId,
                                 positionMs = position ?: 0L,
+                                shuffle = shuffle,
                             )
 
                         if (itemDestination is Destination.Playback) {
diff --git a/app/src/main/java/com/github/damontecres/wholphin/ui/nav/Destination.kt b/app/src/main/java/com/github/damontecres/wholphin/ui/nav/Destination.kt
index d9d027fc..081b18d0 100644
--- a/app/src/main/java/com/github/damontecres/wholphin/ui/nav/Destination.kt
+++ b/app/src/main/java/com/github/damontecres/wholphin/ui/nav/Destination.kt
@@ -90,6 +90,7 @@ sealed class Destination(
         val positionMs: Long,
         val forceTranscoding: Boolean = false,
         val backend: PlayerBackend? = null,
+        val shuffle: Boolean = false,
     ) : Destination(true) {
         constructor(item: BaseItem) : this(item.id, item.resumeMs)
     }
diff --git a/app/src/main/java/com/github/damontecres/wholphin/ui/playback/PlaybackViewModel.kt b/app/src/main/java/com/github/damontecres/wholphin/ui/playback/PlaybackViewModel.kt
index 6587e758..ceade4c0 100644
--- a/app/src/main/java/com/github/damontecres/wholphin/ui/playback/PlaybackViewModel.kt
+++ b/app/src/main/java/com/github/damontecres/wholphin/ui/playback/PlaybackViewModel.kt
@@ -332,10 +332,17 @@ class PlaybackViewModel
                                 filter = destination.filter,
                             )
                         } else {
+                            val shuffled =
+                                if (destination is Destination.Playback) {
+                                    destination.shuffle
+                                } else {
+                                    false
+                                }
                             // Try to create a playlist
                             playlistCreator.createFrom(
                                 item = queriedItem,
                                 recursive = true,
+                                shuffled = shuffled,
                             )
                         }
                     when (val r = playlistResult) {