diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..58c62231e1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,29 @@
+# AGENTS.md
+
+## Build
+
+### APK Build Command
+```bash
+JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./gradlew :smarttubetv:assembleStstableDebug
+```
+
+### Java Version Fix
+AGP 7.4.2 + Java 21 causes a D8 NPE during dexing (`VideoCardPresenter$2.class`). Must use Java 17:
+```bash
+export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
+```
+
+### Module Compilation (fast check, no APK)
+```bash
+./gradlew :common:compileStstableDebugJavaWithJavac
+```
+
+### Install to TV
+```bash
+adb connect <ip>:<port>
+adb install -r <apk>
+# If signature mismatch: adb uninstall <package> && adb install <apk>
+```
+
+### Package Name
+- `org.smarttube.stable` (stable flavor)
diff --git a/common/build.gradle b/common/build.gradle
index 35466e810e..b2dc6acc3b 100644
--- a/common/build.gradle
+++ b/common/build.gradle
@@ -11,7 +11,10 @@ android {
 
     compileSdkVersion project.properties.compileSdkVersion
     buildToolsVersion project.properties.buildToolsVersion
-    testOptions.unitTests.includeAndroidResources = true
+    testOptions {
+        unitTests.includeAndroidResources = true
+        unitTests.returnDefaultValues = true
+    }
 
     defaultConfig {
         minSdkVersion project.properties.minSdkVersion
@@ -57,6 +60,7 @@ dependencies {
     implementation 'androidx.appcompat:appcompat:' + appCompatXVersion
     testImplementation 'junit:junit:' + junitVersion
     testImplementation 'org.robolectric:robolectric:' + robolectricVersion
+    testImplementation 'org.mockito:mockito-core:' + mockitoVersion
 
     implementation project(':sharedutils')
     implementation project(':fragment-1.1.0')
@@ -103,4 +107,7 @@ dependencies {
     implementation project(':appupdatechecker2')
 
     implementation project(':slidableactivity') // https://github.com/r0adkll/Slidr
+
+    implementation 'org.nanohttpd:nanohttpd:2.3.1'
+    implementation 'org.nanohttpd:nanohttpd-websocket:2.3.1'
 }
diff --git a/common/src/main/AndroidManifest.xml b/common/src/main/AndroidManifest.xml
index cfb7b4ecc4..1cd71f0800 100644
--- a/common/src/main/AndroidManifest.xml
+++ b/common/src/main/AndroidManifest.xml
@@ -1,5 +1,7 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
+          xmlns:tools="http://schemas.android.com/tools"
           package="com.liskovsoft.smartyoutubetv2.common">
+    <uses-sdk tools:overrideLibrary="androidx.test.espresso.idling.resource,androidx.test.monitor,androidx.test.core,androidx.test.ext.junit,androidx.test.ext.truth,androidx.test.runner,androidx.test.rules,androidx.test.espresso" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <!-- Android 14 (API 34) -->
     <!-- <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE" /> -->
@@ -19,6 +21,7 @@
     <!-- Starting targetSDK 33+, foreground services require explicit permissions in the manifest. -->
     <!-- NOTE: only works with 'mediaPlayback' type service. Others types will fail. -->
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"/>
+    <uses-permission android:name="android.permission.INTERNET" />
 
     <queries>
         <!-- Android 11+: access package info (works only for specified apps) -->
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/models/data/Playlist.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/models/data/Playlist.java
index 3107327107..f600046a9e 100644
--- a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/models/data/Playlist.java
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/models/data/Playlist.java
@@ -16,6 +16,7 @@ public class Playlist {
     private final List<Video> mPlaylist;
     private final List<Video> mSyncedItems;
     private int mCurrentIndex;
+    private volatile int mGeneration;
     private static Playlist sInstance;
 
     private Playlist() {
@@ -39,18 +40,57 @@ public static Playlist instance() {
     public void clear() {
         mPlaylist.clear();
         mCurrentIndex = -1;
+        mGeneration++;
     }
 
     public void clearPosition() {
         mCurrentIndex = -1;
     }
 
+    /**
+     * Shuffles the playlist while keeping the currently-playing item as current.
+     */
+    public void shuffle() {
+        if (mPlaylist.isEmpty()) {
+            return;
+        }
+        Video current = getCurrent();
+        Collections.shuffle(mPlaylist);
+        if (current != null) {
+            int newIndex = mPlaylist.indexOf(current);
+            mCurrentIndex = newIndex >= 0 ? newIndex : 0;
+        } else {
+            mCurrentIndex = 0;
+        }
+        mGeneration++;
+    }
+
+    /**
+     * Reorders one item in the playlist while keeping the current pointer correct.
+     */
+    public void move(int fromIndex, int toIndex) {
+        if (mPlaylist.isEmpty() || fromIndex == toIndex) {
+            return;
+        }
+        if (fromIndex < 0 || fromIndex >= mPlaylist.size() || toIndex < 0 || toIndex >= mPlaylist.size()) {
+            return;
+        }
+        Video current = getCurrent();
+        Video moved = mPlaylist.remove(fromIndex);
+        mPlaylist.add(toIndex, moved);
+        if (current != null) {
+            mCurrentIndex = mPlaylist.indexOf(current);
+        }
+        mGeneration++;
+    }
+
     /**
      * Used to sync list with remotely added items
      */
     public void addAll(List<Video> videos) {
         mPlaylist.removeAll(videos);
         mPlaylist.addAll(videos);
+        mGeneration++;
     }
 
     /**
@@ -87,6 +127,8 @@ public void add(Video video) {
         // In this case remove all next items.
         trimPlaylist();
         stripPrevItem();
+
+        mGeneration++;
     }
 
     public void next(Video video) {
@@ -109,6 +151,8 @@ public void next(Video video) {
         // In this case remove all next items.
         trimPlaylist();
         stripPrevItem();
+
+        mGeneration++;
     }
 
     public void remove(Video video) {
@@ -140,6 +184,8 @@ public void remove(Video video) {
                 mCurrentIndex = mPlaylist.size() - 1;
             }
         }
+
+        mGeneration++;
     }
 
     public boolean contains(Video video) {
@@ -320,6 +366,10 @@ private void replace(Video origin, Video newItem) {
         }
     }
 
+    public int getGeneration() {
+        return mGeneration;
+    }
+
     public void onNewSession() {
         mSyncedItems.clear();
     }
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/models/playback/controllers/SuggestionsController.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/models/playback/controllers/SuggestionsController.java
index fbee02de43..5d34742749 100644
--- a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/models/playback/controllers/SuggestionsController.java
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/models/playback/controllers/SuggestionsController.java
@@ -46,7 +46,9 @@ public class SuggestionsController extends BasePlayerController {
     private Video mNextSectionVideo;
     private int mFocusCount;
     private int mNextRetryCount;
-    private List<ChapterItem> mChapters;
+    // Written on the main thread (metadata load), but also read from NanoHTTPD worker
+    // threads via the remote API (RemoteApiBridge.getChapters) — volatile for visibility.
+    private volatile List<ChapterItem> mChapters;
     private final Runnable mChapterHandler = this::startChapterNotificationServiceIfNeededInt;
     private static final int MAX_PLAYLIST_CONTINUATIONS = 20;
     private static final int CHAPTER_NOTIFICATION_Id = 565;
@@ -354,6 +356,9 @@ private void updateSuggestions(MediaItemMetadata mediaItemMetadata, Video video)
 
         // After video suggestions
         callListener(mediaItemMetadata);
+
+        // Notify remote API clients that suggestions have been updated
+        com.liskovsoft.smartyoutubetv2.common.misc.remoteapi.RemoteApiBridge.notifySuggestionsUpdated();
     }
 
     private void appendSuggestions(Video video, MediaItemMetadata mediaItemMetadata) {
@@ -546,6 +551,14 @@ private void startChapterNotificationServiceIfNeededInt() {
         }
     }
 
+    /**
+     * Chapters of the currently playing video (parsed from YouTube metadata),
+     * or null when the video has none / nothing is playing. Used by the remote API.
+     */
+    public List<ChapterItem> getChapters() {
+        return mChapters;
+    }
+
     private void appendChaptersIfNeeded(MediaItemMetadata mediaItemMetadata) {
         mChapters = mediaItemMetadata.getChapters();
         
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/models/playback/controllers/VideoStateController.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/models/playback/controllers/VideoStateController.java
index 118b56e90d..92f119583e 100644
--- a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/models/playback/controllers/VideoStateController.java
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/models/playback/controllers/VideoStateController.java
@@ -613,14 +613,8 @@ private void restoreVolume() {
 
         float newVolume = getPlayerData().getPlayerVolume();
 
-        if (getPlayerTweaksData().isPlayerAutoVolumeEnabled()) {
-            //newVolume *= getVideo().volume;
-            //newVolume = getVideo().volume;
-            if (newVolume < 1f) {
-                newVolume *= getVideo().volume;
-            } else {
-                newVolume = getVideo().volume;
-            }
+        if (getPlayerTweaksData().isPlayerAutoVolumeEnabled() && newVolume < 1f) {
+            newVolume *= getVideo().volume;
         }
 
         if (getVideo().isShorts) {
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/presenters/PlaybackPresenter.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/presenters/PlaybackPresenter.java
index 3514d8fbb6..a1d69743da 100644
--- a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/presenters/PlaybackPresenter.java
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/presenters/PlaybackPresenter.java
@@ -25,6 +25,7 @@
 import com.liskovsoft.smartyoutubetv2.common.app.presenters.dialogs.menu.VideoMenuPresenter;
 import com.liskovsoft.smartyoutubetv2.common.app.views.PlaybackView;
 import com.liskovsoft.smartyoutubetv2.common.exoplayer.selector.FormatItem;
+import com.liskovsoft.smartyoutubetv2.common.misc.remoteapi.RemoteApiBridge;
 import com.liskovsoft.smartyoutubetv2.common.utils.Utils;
 import com.liskovsoft.smartyoutubetv2.common.utils.Utils.ChainProcessor;
 import com.liskovsoft.smartyoutubetv2.common.utils.Utils.Processor;
@@ -61,6 +62,7 @@ private PlaybackPresenter(Context context) {
         mEventListeners.add(new ErrorFixerController());
         mEventListeners.add(new PlayerUIController());
         mEventListeners.add(new RemoteController(context));
+        RemoteApiBridge.init(this);
         mEventListeners.add(new SponsorBlockController());
         mEventListeners.add(new AutoFrameRateController());
         mEventListeners.add(new HQDialogController());
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/presenters/settings/RemoteApiSettingsPresenter.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/presenters/settings/RemoteApiSettingsPresenter.java
new file mode 100644
index 0000000000..702e7be07d
--- /dev/null
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/app/presenters/settings/RemoteApiSettingsPresenter.java
@@ -0,0 +1,159 @@
+package com.liskovsoft.smartyoutubetv2.common.app.presenters.settings;
+
+import android.annotation.SuppressLint;
+import android.content.Context;
+import android.content.Intent;
+
+import com.liskovsoft.sharedutils.helpers.MessageHelpers;
+import com.liskovsoft.smartyoutubetv2.common.R;
+import com.liskovsoft.smartyoutubetv2.common.app.models.playback.ui.OptionItem;
+import com.liskovsoft.smartyoutubetv2.common.app.models.playback.ui.UiOptionItem;
+import com.liskovsoft.smartyoutubetv2.common.app.presenters.AppDialogPresenter;
+import com.liskovsoft.smartyoutubetv2.common.app.presenters.base.BasePresenter;
+import com.liskovsoft.smartyoutubetv2.common.misc.remoteapi.RemoteApiAuthProvider;
+import com.liskovsoft.smartyoutubetv2.common.misc.remoteapi.RemoteApiServer;
+import com.liskovsoft.smartyoutubetv2.common.prefs.RemoteApiData;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class RemoteApiSettingsPresenter extends BasePresenter<Void> {
+    @SuppressLint("StaticFieldLeak")
+    private static RemoteApiSettingsPresenter sInstance;
+    private final RemoteApiData mRemoteApiData;
+    private final RemoteApiAuthProvider mAuthProvider;
+
+    public RemoteApiSettingsPresenter(Context context) {
+        super(context);
+        mRemoteApiData = RemoteApiData.instance(context);
+        mAuthProvider = new RemoteApiAuthProvider(mRemoteApiData);
+    }
+
+    public static RemoteApiSettingsPresenter instance(Context context) {
+        if (sInstance == null) {
+            sInstance = new RemoteApiSettingsPresenter(context);
+        }
+
+        sInstance.setContext(context);
+
+        return sInstance;
+    }
+
+    public void unhold() {
+        sInstance = null;
+    }
+
+    public void show() {
+        createAndShowDialog();
+    }
+
+    private void createAndShowDialog() {
+        AppDialogPresenter settingsPresenter = AppDialogPresenter.instance(getContext());
+
+        appendEnableSwitch(settingsPresenter);
+        appendAllowAllSwitch(settingsPresenter);
+        appendStatusText(settingsPresenter);
+        appendShowCodeButton(settingsPresenter);
+        appendPortCategory(settingsPresenter);
+        appendDeviceNameCategory(settingsPresenter);
+        appendRemoveAllDevicesButton(settingsPresenter);
+        appendDebugButton(settingsPresenter);
+
+        settingsPresenter.showDialog(getContext().getString(R.string.settings_remote_api), this::unhold);
+    }
+
+    private void appendEnableSwitch(AppDialogPresenter settingsPresenter) {
+        settingsPresenter.appendSingleSwitch(UiOptionItem.from(getContext().getString(R.string.remote_api_enable), optionItem -> {
+            mRemoteApiData.enableApi(optionItem.isSelected());
+
+            if (optionItem.isSelected()) {
+                RemoteApiServer.startRemoteApi(getContext());
+            } else {
+                RemoteApiServer.stopRemoteApi(getContext());
+            }
+        }, mRemoteApiData.isApiEnabled()));
+    }
+
+    private void appendAllowAllSwitch(AppDialogPresenter settingsPresenter) {
+        settingsPresenter.appendSingleSwitch(UiOptionItem.from(
+                getContext().getString(R.string.remote_api_allow_all),
+                optionItem -> mRemoteApiData.setAllowAllConnections(optionItem.isSelected()),
+                mRemoteApiData.isAllowAllConnections()));
+    }
+
+    private void appendStatusText(AppDialogPresenter settingsPresenter) {
+        List<OptionItem> options = new ArrayList<>();
+
+        String status;
+        if (mRemoteApiData.isApiEnabled()) {
+            status = getContext().getString(R.string.remote_api_status_running);
+        } else {
+            status = getContext().getString(R.string.remote_api_status_stopped);
+        }
+
+        String statusText = getContext().getString(R.string.remote_api_status, status, mRemoteApiData.getPort());
+        options.add(UiOptionItem.from(statusText));
+
+        settingsPresenter.appendStringsCategory(null, options);
+    }
+
+    private void appendShowCodeButton(AppDialogPresenter settingsPresenter) {
+        settingsPresenter.appendSingleButton(UiOptionItem.from(
+                getContext().getString(R.string.remote_api_show_code), option -> {
+                    String code = mAuthProvider.generatePairingCode();
+                    String message = getContext().getString(R.string.remote_api_current_code, code);
+                    MessageHelpers.showMessage(getContext(), message);
+                }));
+    }
+
+    private void appendPortCategory(AppDialogPresenter settingsPresenter) {
+        List<OptionItem> options = new ArrayList<>();
+
+        options.add(UiOptionItem.from(String.valueOf(mRemoteApiData.getPort()), option -> {
+            mRemoteApiData.setPort(Integer.parseInt(option.getData().toString()));
+            MessageHelpers.showMessage(getContext(), getContext().getString(R.string.remote_api_restart_port));
+        }));
+
+        settingsPresenter.appendStringsCategory(getContext().getString(R.string.remote_api_port), options);
+    }
+
+    private void appendDeviceNameCategory(AppDialogPresenter settingsPresenter) {
+        List<OptionItem> options = new ArrayList<>();
+
+        options.add(UiOptionItem.from(mRemoteApiData.getDeviceName(), option -> {
+            mRemoteApiData.setDeviceName(option.getData().toString());
+        }));
+
+        settingsPresenter.appendStringsCategory(getContext().getString(R.string.remote_api_device_name), options);
+    }
+
+    private void appendRemoveAllDevicesButton(AppDialogPresenter settingsPresenter) {
+        List<OptionItem> options = new ArrayList<>();
+
+        OptionItem confirmItem = UiOptionItem.from(
+                getContext().getString(R.string.btn_confirm), option -> {
+                    mRemoteApiData.removeAllTokens();
+                    MessageHelpers.showMessage(getContext(), R.string.msg_done);
+                    settingsPresenter.closeDialog();
+                }
+        );
+
+        options.add(confirmItem);
+
+        settingsPresenter.appendStringsCategory(getContext().getString(R.string.remote_api_remove_all), options);
+    }
+
+    private void appendDebugButton(AppDialogPresenter settingsPresenter) {
+        settingsPresenter.appendSingleButton(UiOptionItem.from(
+                getContext().getString(R.string.remote_api_debug), option -> {
+                    try {
+                        Intent intent = new Intent();
+                        intent.setClassName(getContext(),
+                                "com.liskovsoft.smartyoutubetv2.tv.ui.debug.RemoteApiDebugActivity");
+                        getContext().startActivity(intent);
+                    } catch (Exception e) {
+                        MessageHelpers.showMessage(getContext(), "Debug activity not found: " + e.getMessage());
+                    }
+                }));
+    }
+}
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/AppDataSourceManager.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/AppDataSourceManager.java
index 5e3ed0317a..7babdfa068 100644
--- a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/AppDataSourceManager.java
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/AppDataSourceManager.java
@@ -15,6 +15,7 @@
 import com.liskovsoft.smartyoutubetv2.common.app.presenters.settings.LanguageSettingsPresenter;
 import com.liskovsoft.smartyoutubetv2.common.app.presenters.settings.MainUISettingsPresenter;
 import com.liskovsoft.smartyoutubetv2.common.app.presenters.settings.PlayerSettingsPresenter;
+import com.liskovsoft.smartyoutubetv2.common.app.presenters.settings.RemoteApiSettingsPresenter;
 import com.liskovsoft.smartyoutubetv2.common.app.presenters.settings.RemoteControlSettingsPresenter;
 import com.liskovsoft.smartyoutubetv2.common.app.presenters.settings.SearchSettingsPresenter;
 import com.liskovsoft.smartyoutubetv2.common.app.presenters.settings.SubtitleSettingsPresenter;
@@ -45,6 +46,8 @@ public List<SettingsItem> getSettingItems(Context context) {
                 context.getString(R.string.settings_accounts), () -> AccountSettingsPresenter.instance(context).show(), R.drawable.settings_account));
         settingItems.add(new SettingsItem(
                 context.getString(R.string.settings_remote_control), () -> RemoteControlSettingsPresenter.instance(context).show(), R.drawable.settings_cast));
+        settingItems.add(new SettingsItem(
+                context.getString(R.string.settings_remote_api), () -> RemoteApiSettingsPresenter.instance(context).show(), R.drawable.settings_cast));
         settingItems.add(new SettingsItem(
                 context.getString(R.string.settings_language_country), () -> LanguageSettingsPresenter.instance(context).show(), R.drawable.settings_language));
         settingItems.add(new SettingsItem(
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/MotherActivity.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/MotherActivity.java
index d694cf9d25..8a7863e11e 100644
--- a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/MotherActivity.java
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/MotherActivity.java
@@ -43,6 +43,9 @@ public class MotherActivity extends FragmentActivity {
     private static final float DEFAULT_WIDTH = 1920f; // xhdpi
     private static DisplayMetrics sCachedDisplayMetrics;
     protected static boolean sIsInPipMode;
+    // The currently-resumed activity, so remote-control key events (e.g. the D-pad remote API)
+    // can be dispatched into the app's own view hierarchy instead of via Instrumentation.
+    private static MotherActivity sCurrentActivity;
     private ScreensaverManager mScreensaverManager;
     // Make static in case Don't keep activities enabled in Developer settings
     private static List<OnPermissions> mOnPermissions;
@@ -193,6 +196,11 @@ protected void attachBaseContext(Context context) {
         super.attachBaseContext(contextWrapper);
     }
 
+    /** The currently-resumed MotherActivity, or null. Used to deliver remote-control key events. */
+    public static MotherActivity getCurrentActivity() {
+        return sCurrentActivity;
+    }
+
     @Override
     protected void onResume() {
         try {
@@ -201,6 +209,8 @@ protected void onResume() {
             e.printStackTrace();
         }
 
+        sCurrentActivity = this;
+
         // 4K fix with AFR
         applyCustomConfig();
 
@@ -215,6 +225,10 @@ protected void onResume() {
     protected void onPause() {
         super.onPause();
 
+        if (sCurrentActivity == this) {
+            sCurrentActivity = null;
+        }
+
         // Remove screensaver from the previous activity when closing current one.
         // Called on player's next track. Reason unknown.
         mScreensaverManager.disable();
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/RemoteControlService.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/RemoteControlService.java
index a5fa3243fd..f76648c7ce 100644
--- a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/RemoteControlService.java
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/RemoteControlService.java
@@ -12,6 +12,8 @@
 import com.liskovsoft.smartyoutubetv2.common.R;
 import com.liskovsoft.smartyoutubetv2.common.app.presenters.PlaybackPresenter;
 import com.liskovsoft.smartyoutubetv2.common.app.views.ViewManager;
+import com.liskovsoft.smartyoutubetv2.common.misc.remoteapi.RemoteApiServer;
+import com.liskovsoft.smartyoutubetv2.common.prefs.RemoteApiData;
 import com.liskovsoft.smartyoutubetv2.common.utils.Utils;
 
 public class RemoteControlService extends Service {
@@ -49,6 +51,10 @@ public int onStartCommand(Intent intent, int flags, int startId) {
         PlaybackPresenter.instance(getApplicationContext()); // init RemoteControlListener
         StreamReminderService.instance(getApplicationContext()).startStop(); // init reminder service
 
+        if (RemoteApiData.instance(this).isApiEnabled()) {
+            RemoteApiServer.startRemoteApi(this);
+        }
+
         return START_STICKY;
     }
 
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/HomeTheaterController.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/HomeTheaterController.java
new file mode 100644
index 0000000000..e8f0e2bdad
--- /dev/null
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/HomeTheaterController.java
@@ -0,0 +1,190 @@
+package com.liskovsoft.smartyoutubetv2.common.misc.remoteapi;
+
+import android.content.Context;
+import android.media.AudioDeviceInfo;
+import android.media.AudioManager;
+
+import com.liskovsoft.sharedutils.mylogger.Log;
+
+import org.json.JSONException;
+import org.json.JSONObject;
+
+/**
+ * Home theater audio control — wraps AudioManager for volume/mute.
+ * HDMI CEC features (output switching, subwoofer/rear levels, sound mode,
+ * immersive AE) require ADB shell access and should be implemented by
+ * the Chrome extension or an ADB bridge.
+ *
+ * @see docs/remote-control-api.md section 4.10 for ADB commands.
+ */
+public class HomeTheaterController {
+    private static final String TAG = HomeTheaterController.class.getSimpleName();
+    private static final int STREAM_MUSIC = AudioManager.STREAM_MUSIC;
+
+    private static HomeTheaterController sInstance;
+    private final Context mContext;
+    private final AudioManager mAudioManager;
+
+    private HomeTheaterController(Context context) {
+        mContext = context.getApplicationContext();
+        mAudioManager = (AudioManager) mContext.getSystemService(Context.AUDIO_SERVICE);
+    }
+
+    public static synchronized HomeTheaterController instance(Context context) {
+        if (sInstance == null) {
+            sInstance = new HomeTheaterController(context);
+        }
+        return sInstance;
+    }
+
+    // ---- Volume (via AudioManager) ----
+
+    public int getVolume() {
+        int raw = mAudioManager.getStreamVolume(STREAM_MUSIC);
+        int max = mAudioManager.getStreamMaxVolume(STREAM_MUSIC);
+        return max > 0 ? Math.round(raw * 100f / max) : 0;
+    }
+
+    public void setVolume(int volume) {
+        int clamped = Math.max(0, Math.min(100, volume));
+        int max = mAudioManager.getStreamMaxVolume(STREAM_MUSIC);
+        int targetRaw = max > 0 ? Math.round(clamped * max / 100f) : 0;
+
+        // Try an absolute set first (works when the TV's own speakers are active).
+        mAudioManager.setStreamVolume(STREAM_MUSIC, targetRaw, 0);
+
+        // With a CEC audio system (soundbar/HT) the absolute set is silently ignored —
+        // CEC only understands volume-key steps. Measured on a Sony HT-A9: steps need
+        // ~200ms pacing or the device drops them, and the volume reported back via CEC
+        // <Report Audio Status> lags 1-2s. A single PERSISTENT worker walks toward the
+        // target counting its own steps (re-reading mid-ramp returns stale values);
+        // new setVolume calls just retarget it — never cancel/restart, otherwise a
+        // burst of slider updates strangles the ramp after one step each.
+        synchronized (sRampLock) {
+            sTargetRaw = targetRaw;
+            if (sRampThread == null || !sRampThread.isAlive()) {
+                sRampThread = new Thread(this::rampWorker, "TheaterVolumeRamp");
+                sRampThread.start();
+            }
+        }
+    }
+
+    private void rampWorker() {
+        int expected = mAudioManager.getStreamVolume(STREAM_MUSIC);
+        int verifyPasses = 0;
+        while (true) {
+            int target;
+            synchronized (sRampLock) {
+                target = sTargetRaw;
+            }
+            int delta = target - expected;
+            if (delta != 0) {
+                verifyPasses = 0;
+                mAudioManager.adjustStreamVolume(STREAM_MUSIC,
+                        delta > 0 ? AudioManager.ADJUST_RAISE : AudioManager.ADJUST_LOWER, 0);
+                expected += delta > 0 ? 1 : -1;
+                if (!sleepQuiet(220)) {
+                    return;
+                }
+                continue;
+            }
+            // Reached target by our own count. Wait for the lagging CEC report,
+            // then verify once; correct drift with a bounded number of passes.
+            if (!sleepQuiet(1500)) {
+                return;
+            }
+            int actual = mAudioManager.getStreamVolume(STREAM_MUSIC);
+            synchronized (sRampLock) {
+                if (sTargetRaw != target) {
+                    continue; // retargeted while settling — keep going from our count
+                }
+                if (actual == target || verifyPasses >= 2) {
+                    sRampThread = null;
+                    return;
+                }
+            }
+            expected = actual;
+            verifyPasses++;
+        }
+    }
+
+    private static boolean sleepQuiet(long ms) {
+        try {
+            Thread.sleep(ms);
+            return true;
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            return false;
+        }
+    }
+
+    private static final Object sRampLock = new Object();
+    private static int sTargetRaw = -1;
+    private static Thread sRampThread;
+
+    public void volumeUp() {
+        mAudioManager.adjustStreamVolume(STREAM_MUSIC, AudioManager.ADJUST_RAISE, 0);
+    }
+
+    public void volumeDown() {
+        mAudioManager.adjustStreamVolume(STREAM_MUSIC, AudioManager.ADJUST_LOWER, 0);
+    }
+
+    public boolean isMuted() {
+        return mAudioManager.getStreamVolume(STREAM_MUSIC) == 0;
+    }
+
+    public void toggleMute() {
+        int current = mAudioManager.getStreamVolume(STREAM_MUSIC);
+        if (current > 0) {
+            mAudioManager.setStreamVolume(STREAM_MUSIC, 0, 0);
+        } else {
+            mAudioManager.setStreamVolume(STREAM_MUSIC, mAudioManager.getStreamMaxVolume(STREAM_MUSIC) / 2, 0);
+        }
+    }
+
+    // ---- Power ----
+
+    public void togglePower() {
+        try {
+            Runtime.getRuntime().exec(new String[]{"input", "keyevent", "KEYCODE_POWER"});
+        } catch (Exception e) {
+            Log.e(TAG, "togglePower failed: %s", e.getMessage());
+        }
+    }
+
+    // ---- Audio Output (detected via AudioManager) ----
+
+    /**
+     * Detect current audio output device.
+     * Returns "theater" if audio is routed to HDMI/ARC/eARC (home theater),
+     * "tv" if routed to built-in speakers.
+     */
+    public String getAudioOutput() {
+        AudioDeviceInfo[] devices = mAudioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS);
+        for (AudioDeviceInfo device : devices) {
+            int type = device.getType();
+            if (type == AudioDeviceInfo.TYPE_HDMI
+                    || type == AudioDeviceInfo.TYPE_HDMI_ARC
+                    || type == AudioDeviceInfo.TYPE_HDMI_EARC
+                    || type == AudioDeviceInfo.TYPE_WIRED_HEADPHONES) {
+                return "theater";
+            }
+        }
+        return "tv";
+    }
+
+    // ---- Full State ----
+
+    public JSONObject getState() {
+        try {
+            JSONObject state = new JSONObject();
+            state.put("volume", getVolume());
+            state.put("muted", isMuted());
+            state.put("audio_output", getAudioOutput());
+            return state;
+        } catch (JSONException e) {
+            return new JSONObject();
+        }
+    }
+}
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/RemoteApiAuthProvider.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/RemoteApiAuthProvider.java
new file mode 100644
index 0000000000..1f4c9a1415
--- /dev/null
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/RemoteApiAuthProvider.java
@@ -0,0 +1,136 @@
+package com.liskovsoft.smartyoutubetv2.common.misc.remoteapi;
+
+import com.liskovsoft.smartyoutubetv2.common.prefs.RemoteApiData;
+
+import java.security.SecureRandom;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+public class RemoteApiAuthProvider {
+    private static final int PAIRING_CODE_LENGTH = 6;
+    private static final long PAIRING_CODE_EXPIRY_MS = 5 * 60 * 1000;
+    private static final int TOKEN_BYTE_LENGTH = 32;
+    private static final int MAX_FAILED_ATTEMPTS = 5;
+    private static final long RATE_LIMIT_WINDOW_MS = 60 * 1000;
+
+    // Index into the per-IP long[] state: [count, windowStartMs]
+    private static final int IDX_COUNT = 0;
+    private static final int IDX_TIMESTAMP = 1;
+
+    private final RemoteApiData mApiData;
+    private final SecureRandom mSecureRandom;
+    // Accessed concurrently from NanoHTTPD request threads, so use a concurrent map.
+    // The value holds a 64-bit timestamp, so it must be long[] (an int can't hold currentTimeMillis()).
+    private final Map<String, long[]> mFailedAttempts;
+
+    public RemoteApiAuthProvider(RemoteApiData apiData) {
+        mApiData = apiData;
+        mSecureRandom = new SecureRandom();
+        mFailedAttempts = new ConcurrentHashMap<>();
+    }
+
+    public String generatePairingCode() {
+        StringBuilder codeBuilder = new StringBuilder();
+
+        for (int i = 0; i < PAIRING_CODE_LENGTH; i++) {
+            int digit = mSecureRandom.nextInt(10);
+            codeBuilder.append(digit);
+
+            if (i == 2) {
+                codeBuilder.append(" ");
+            }
+        }
+
+        String code = codeBuilder.toString();
+        long expiryMs = System.currentTimeMillis() + PAIRING_CODE_EXPIRY_MS;
+
+        mApiData.setPairingCode(code, expiryMs);
+
+        return code;
+    }
+
+    public String verifyPairingCode(String code, String clientIp) {
+        if (!checkRateLimit(clientIp)) {
+            return null;
+        }
+
+        // Atomically validate AND invalidate the code: a second concurrent verify with
+        // the same code must fail (one code, one token), closing the double-issue race.
+        if (code == null || !mApiData.consumePairingCode(code)) {
+            recordFailedAttempt(clientIp);
+            return null;
+        }
+
+        String token = generateToken();
+
+        mApiData.addPairedToken(token, null);
+        resetFailedAttempts(clientIp);
+
+        return token;
+    }
+
+    public boolean isTokenValid(String token) {
+        return mApiData.isTokenValid(token);
+    }
+
+    /** True when the client has exceeded the pairing rate limit and should be told to back off. */
+    public boolean isRateLimited(String clientIp) {
+        return !checkRateLimit(clientIp);
+    }
+
+    public void revokeAllTokens() {
+        mApiData.removeAllTokens();
+    }
+
+    private String generateToken() {
+        byte[] tokenBytes = new byte[TOKEN_BYTE_LENGTH];
+        mSecureRandom.nextBytes(tokenBytes);
+
+        StringBuilder hexBuilder = new StringBuilder();
+        for (byte b : tokenBytes) {
+            hexBuilder.append(String.format("%02x", b & 0xff));
+        }
+
+        return hexBuilder.toString();
+    }
+
+    private boolean checkRateLimit(String clientIp) {
+        if (clientIp == null) {
+            return true;
+        }
+
+        long[] attempts = mFailedAttempts.get(clientIp);
+        if (attempts == null) {
+            return true;
+        }
+
+        long now = System.currentTimeMillis();
+        if (now - attempts[IDX_TIMESTAMP] > RATE_LIMIT_WINDOW_MS) {
+            mFailedAttempts.remove(clientIp);
+            return true;
+        }
+
+        return attempts[IDX_COUNT] < MAX_FAILED_ATTEMPTS;
+    }
+
+    private void recordFailedAttempt(String clientIp) {
+        if (clientIp == null) {
+            return;
+        }
+
+        long now = System.currentTimeMillis();
+        long[] attempts = mFailedAttempts.get(clientIp);
+
+        if (attempts == null || now - attempts[IDX_TIMESTAMP] > RATE_LIMIT_WINDOW_MS) {
+            mFailedAttempts.put(clientIp, new long[]{1, now});
+        } else {
+            attempts[IDX_COUNT]++;
+        }
+    }
+
+    private void resetFailedAttempts(String clientIp) {
+        if (clientIp != null) {
+            mFailedAttempts.remove(clientIp);
+        }
+    }
+}
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/RemoteApiBridge.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/RemoteApiBridge.java
new file mode 100644
index 0000000000..d6c8d9409f
--- /dev/null
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/RemoteApiBridge.java
@@ -0,0 +1,1240 @@
+package com.liskovsoft.smartyoutubetv2.common.misc.remoteapi;
+
+import android.content.Context;
+import android.net.Uri;
+import android.os.Handler;
+import android.os.Looper;
+import android.view.KeyEvent;
+
+import com.liskovsoft.mediaserviceinterfaces.ContentService;
+import com.liskovsoft.mediaserviceinterfaces.data.ChapterItem;
+import com.liskovsoft.mediaserviceinterfaces.data.MediaGroup;
+import com.liskovsoft.mediaserviceinterfaces.data.MediaItem;
+import com.liskovsoft.mediaserviceinterfaces.data.MediaItemMetadata;
+import com.liskovsoft.smartyoutubetv2.common.app.models.data.Playlist;
+import com.liskovsoft.smartyoutubetv2.common.app.models.data.Video;
+import com.liskovsoft.smartyoutubetv2.common.app.models.data.VideoGroup;
+import com.liskovsoft.smartyoutubetv2.common.app.models.playback.controllers.SuggestionsController;
+import com.liskovsoft.smartyoutubetv2.common.app.models.playback.controllers.VideoLoaderController;
+import com.liskovsoft.smartyoutubetv2.common.app.models.playback.manager.PlayerUI;
+import com.liskovsoft.smartyoutubetv2.common.app.presenters.PlaybackPresenter;
+import com.liskovsoft.smartyoutubetv2.common.app.presenters.SearchPresenter;
+import com.liskovsoft.smartyoutubetv2.common.app.views.PlaybackView;
+import com.liskovsoft.smartyoutubetv2.common.app.views.ViewManager;
+import com.liskovsoft.smartyoutubetv2.common.exoplayer.selector.FormatItem;
+import com.liskovsoft.smartyoutubetv2.common.exoplayer.selector.TrackSelectorUtil;
+import com.liskovsoft.smartyoutubetv2.common.exoplayer.selector.track.MediaTrack;
+import com.liskovsoft.smartyoutubetv2.common.prefs.PlayerData;
+import com.liskovsoft.smartyoutubetv2.common.utils.Utils;
+import com.liskovsoft.youtubeapi.service.YouTubeServiceManager;
+
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+public class RemoteApiBridge {
+    private static PlaybackPresenter sPresenter;
+    private static RemoteApiServer sServer;
+
+    // Bulk playlist-add caps: bound the blocking continuation loop so a huge playlist
+    // can't tie up a NanoHTTPD worker thread indefinitely or flood the queue.
+    private static final int MAX_PLAYLIST_CONTINUATIONS = 20;
+    private static final int MAX_TOTAL_PLAYLIST_ITEMS = 500;
+
+    // The player exposes suggestions as indexed groups with no count; scan until the
+    // first null group. Bound the scan so a misbehaving provider can't spin forever.
+    private static final int MAX_SUGGESTION_GROUPS = 50;
+
+    // Mutated and read from NanoHTTPD request/WebSocket threads; volatile guarantees visibility.
+    private static volatile int sZoomPercents = 100;
+    private static volatile int sRotationAngle = 0;
+    private static volatile boolean sFlipEnabled = false;
+    private static volatile float sPreviousVolume = 1.0f;
+
+    public static void init(PlaybackPresenter presenter) {
+        sPresenter = presenter;
+    }
+
+    public static void setServer(RemoteApiServer server) {
+        sServer = server;
+    }
+
+    private static final Handler sMainHandler = new Handler(Looper.getMainLooper());
+
+    // API commands arrive on NanoHTTPD worker threads, but ExoPlayer and the playback
+    // controllers must only be touched from the main thread — calling them off-thread
+    // makes commands like next/previous silently fail (or crash). All mutators post here.
+    private static void runOnMainThread(Runnable action) {
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            action.run();
+        } else {
+            sMainHandler.post(action);
+        }
+    }
+
+    private static PlaybackView getPlayer() {
+        return sPresenter != null ? sPresenter.getPlayer() : null;
+    }
+
+    @FunctionalInterface
+    private interface PlayerAction {
+        void run(PlaybackView player);
+    }
+
+    // Most mutating commands share the same shape: hop to the main thread, grab the
+    // player, and no-op if it's gone. This bundles that guard so call sites read as
+    // just their payload. (getPlayer() != null also implies sPresenter != null.)
+    private static void withPlayerOnMain(PlayerAction action) {
+        runOnMainThread(() -> {
+            PlaybackView player = getPlayer();
+            if (player != null) {
+                action.run(player);
+            }
+        });
+    }
+
+    /// Prefer the background image (high-res) over the card image (small grid thumb).
+    private static String bestThumbnail(Video video) {
+        if (video.bgImageUrl != null && !video.bgImageUrl.isEmpty()) {
+            return video.bgImageUrl;
+        }
+        return video.getCardImageUrl();
+    }
+
+    // ---- Player State ----
+
+    public static JSONObject getPlayerState() {
+        PlaybackView player = getPlayer();
+        if (player == null || !player.isEngineInitialized()) {
+            try {
+                JSONObject state = new JSONObject();
+                state.put("state", "idle");
+                state.put("suggestions_count", 0);
+                Playlist playlist = Playlist.instance();
+                state.put("queue_size", playlist.getAll().size());
+                state.put("queue_index", playlist.getAll().indexOf(playlist.getCurrent()));
+                state.put("queue_generation", playlist.getGeneration());
+                return state;
+            } catch (JSONException e) {
+                return null;
+            }
+        }
+
+        try {
+            JSONObject state = new JSONObject();
+
+            if (player.isPlaying()) {
+                state.put("state", "playing");
+            } else if (player.getPlayWhenReady()) {
+                state.put("state", "buffering");
+            } else {
+                state.put("state", "idle");
+            }
+
+            Video video = sPresenter.getVideo();
+            if (video != null) {
+                JSONObject videoJson = videoToJson(video);
+                videoJson.put("channel_id", video.channelId);
+                // The player knows the real, resolved duration; prefer it over the card's.
+                videoJson.put("duration_ms", player.getDurationMs());
+                videoJson.put("is_shorts", video.isShorts);
+                videoJson.put("playlist_id", video.getPlaylistId());
+                videoJson.put("playlist_index", video.playlistIndex);
+                state.put("video", videoJson);
+            }
+
+            state.put("position_ms", player.getPositionMs());
+            state.put("duration_ms", player.getDurationMs());
+            state.put("speed", player.getSpeed());
+            state.put("pitch", player.getPitch());
+            state.put("volume", getVolume());
+
+            state.put("selected_tracks", selectedTracksJson(player));
+
+            JSONObject videoTransform = new JSONObject();
+            videoTransform.put("resize_mode", player.getResizeMode());
+            videoTransform.put("zoom_percents", sZoomPercents);
+            videoTransform.put("rotation_angle", sRotationAngle);
+            videoTransform.put("flip_enabled", sFlipEnabled);
+            state.put("video_transform", videoTransform);
+
+            state.put("suggestions_count", countSuggestions(player));
+
+            Playlist playlist = Playlist.instance();
+            state.put("queue_size", playlist.getAll().size());
+            state.put("queue_index", playlist.getAll().indexOf(playlist.getCurrent()));
+            state.put("queue_generation", playlist.getGeneration());
+
+            return state;
+        } catch (JSONException e) {
+            return null;
+        }
+    }
+
+    // ---- Transport Controls ----
+
+    public static void handlePlay() {
+        withPlayerOnMain(player -> player.setPlayWhenReady(true));
+    }
+
+    public static void handlePause() {
+        withPlayerOnMain(player -> player.setPlayWhenReady(false));
+    }
+
+    public static void handleToggle() {
+        withPlayerOnMain(player -> player.setPlayWhenReady(!player.getPlayWhenReady()));
+    }
+
+    public static JSONObject handleSeek(long positionMs) {
+        withPlayerOnMain(player -> player.setPositionMs(positionMs));
+        JSONObject result = new JSONObject();
+        try {
+            result.put("ok", true);
+            result.put("position_ms", positionMs);
+        } catch (JSONException e) {
+            // JSON construction over constant keys can't fail.
+        }
+        return result;
+    }
+
+    // Rapid next/previous presses arrive before the new video's metadata loads,
+    // making VideoLoaderController toast "Please wait while data is loading…".
+    // Drop skips that land within the debounce window.
+    private static volatile long sLastSkipMs;
+    private static final long SKIP_DEBOUNCE_MS = 700;
+
+    private static boolean skipDebounced() {
+        long now = System.currentTimeMillis();
+        if (now - sLastSkipMs < SKIP_DEBOUNCE_MS) {
+            return true;
+        }
+        sLastSkipMs = now;
+        return false;
+    }
+
+    public static void handleNext() {
+        if (skipDebounced()) {
+            return;
+        }
+        withPlayerOnMain(player -> {
+            VideoLoaderController controller = sPresenter.getController(VideoLoaderController.class);
+            if (controller != null) {
+                controller.loadNext();
+            }
+        });
+    }
+
+    public static void handlePrevious() {
+        if (skipDebounced()) {
+            return;
+        }
+        withPlayerOnMain(player -> {
+            VideoLoaderController controller = sPresenter.getController(VideoLoaderController.class);
+            if (controller != null) {
+                controller.loadPrevious();
+            }
+        });
+    }
+
+    public static void handleStop() {
+        withPlayerOnMain(PlaybackView::finish);
+    }
+
+    public static void handleReload() {
+        withPlayerOnMain(PlaybackView::reloadPlayback);
+    }
+
+    // ---- Speed / Volume / Pitch ----
+
+    public static float getSpeed() {
+        PlaybackView player = getPlayer();
+        return player != null ? player.getSpeed() : 1.0f;
+    }
+
+    public static void setSpeed(float speed) {
+        withPlayerOnMain(player -> player.setSpeed(speed));
+    }
+
+    public static float getVolume() {
+        // Report the user's intended volume (PlayerData), NOT player.getVolume():
+        // VideoStateController multiplies the persisted value by the video's loudness
+        // normalization on every load, so reading the effective value back and
+        // persisting it again ratchets the volume lower on each video change.
+        if (sPresenter != null && sPresenter.getContext() != null) {
+            return PlayerData.instance(sPresenter.getContext()).getPlayerVolume();
+        }
+        PlaybackView player = getPlayer();
+        return player != null ? player.getVolume() : 1.0f;
+    }
+
+    public static void setVolume(float volume) {
+        // Accept both the documented normalized form (0.10) and controller/UI
+        // percent values (10). The persisted value is always ExoPlayer's 0..1
+        // gain, matching the macOS "10/100" player-volume command.
+        float normalized = volume > 1f ? volume / 100f : volume;
+
+        // Clamp to 0..1 (the API contract). Persisting a value > 1.0 arms the
+        // VolumeBooster (LoudnessEnhancer) on the next player init — its built-in
+        // limiter audibly compresses/"sidechains" the output. 1.0 is the safe max.
+        // Math.max/min also coerce a non-finite (NaN/Infinity) input to a sane bound.
+        float clamped = Float.isNaN(normalized) ? 1f : Math.max(0f, Math.min(normalized, 1f));
+        // Persist independently of the player: VideoStateController re-applies
+        // PlayerData's volume on every video load, so without this the API value
+        // reverts on the next video — even if no player is attached right now.
+        runOnMainThread(() -> {
+            PlaybackView player = getPlayer();
+            if (player != null) {
+                player.setVolume(clamped);
+            }
+            if (sPresenter != null && sPresenter.getContext() != null) {
+                PlayerData.instance(sPresenter.getContext()).setPlayerVolume(clamped);
+            }
+        });
+    }
+
+    public static float getPitch() {
+        PlaybackView player = getPlayer();
+        return player != null ? player.getPitch() : 1.0f;
+    }
+
+    public static void setPitch(float pitch) {
+        withPlayerOnMain(player -> player.setPitch(pitch));
+    }
+
+    // ---- Format Listing ----
+
+    public static JSONArray getVideoFormats() {
+        PlaybackView player = getPlayer();
+        return player != null ? formatListToJson(player.getVideoFormats()) : new JSONArray();
+    }
+
+    public static JSONArray getAudioFormats() {
+        PlaybackView player = getPlayer();
+        return player != null ? formatListToJson(player.getAudioFormats()) : new JSONArray();
+    }
+
+    public static JSONArray getSubtitleFormats() {
+        PlaybackView player = getPlayer();
+        return player != null ? formatListToJson(player.getSubtitleFormats()) : new JSONArray();
+    }
+
+    public static JSONObject getSelectedTracks() {
+        PlaybackView player = getPlayer();
+        if (player == null) {
+            return new JSONObject();
+        }
+        try {
+            return selectedTracksJson(player);
+        } catch (JSONException e) {
+            return new JSONObject();
+        }
+    }
+
+    private static JSONObject selectedTracksJson(PlaybackView player) throws JSONException {
+        JSONObject result = new JSONObject();
+        result.put("video", formatToJsonObject(player.getVideoFormat()));
+        result.put("audio", formatToJsonObject(player.getAudioFormat()));
+        result.put("subtitle", formatToJsonObject(player.getSubtitleFormat()));
+        return result;
+    }
+
+    // ---- Format Selection ----
+
+    public static void setVideoFormat(String formatId) {
+        withPlayerOnMain(player -> setFormatById(player, player.getVideoFormats(), formatId));
+    }
+
+    public static void setAudioFormat(String formatId) {
+        withPlayerOnMain(player -> setFormatById(player, player.getAudioFormats(), formatId));
+    }
+
+    public static void setSubtitleFormat(String formatId) {
+        withPlayerOnMain(player -> {
+            if (formatId == null || formatId.isEmpty()) {
+                player.setFormat(FormatItem.SUBTITLE_NONE);
+                return;
+            }
+            setFormatById(player, player.getSubtitleFormats(), formatId);
+        });
+    }
+
+    // Find the format matching formatId in the given list and select it; no-op if absent.
+    private static void setFormatById(PlaybackView player, List<FormatItem> formats, String formatId) {
+        if (formatId == null) {
+            return;
+        }
+        FormatItem item = findFormatById(formats, formatId);
+        if (item != null) {
+            player.setFormat(item);
+        }
+    }
+
+    // ---- Video Transform ----
+
+    public static int getResizeMode() {
+        PlaybackView player = getPlayer();
+        return player != null ? player.getResizeMode() : 0;
+    }
+
+    public static void setResizeMode(int mode) {
+        withPlayerOnMain(player -> player.setResizeMode(mode));
+    }
+
+    public static int getZoom() {
+        return sZoomPercents;
+    }
+
+    public static void setZoom(int zoom) {
+        // Track the value even when no player is attached so getZoom() stays accurate.
+        runOnMainThread(() -> {
+            sZoomPercents = zoom;
+            PlaybackView player = getPlayer();
+            if (player != null) {
+                player.setZoomPercents(zoom);
+            }
+        });
+    }
+
+    public static int getRotation() {
+        return sRotationAngle;
+    }
+
+    public static void setRotation(int angle) {
+        runOnMainThread(() -> {
+            sRotationAngle = angle;
+            PlaybackView player = getPlayer();
+            if (player != null) {
+                player.setRotationAngle(angle);
+            }
+        });
+    }
+
+    public static boolean getFlip() {
+        return sFlipEnabled;
+    }
+
+    public static void setFlip(boolean enabled) {
+        runOnMainThread(() -> {
+            sFlipEnabled = enabled;
+            PlaybackView player = getPlayer();
+            if (player != null) {
+                player.setVideoFlipEnabled(enabled);
+            }
+        });
+    }
+
+    public static void notifySuggestionsUpdated() {
+        RemoteApiServer server = RemoteApiServer.getInstance();
+        if (server != null) {
+            try {
+                JSONObject data = new JSONObject();
+                data.put("suggestions_count", countSuggestions(getPlayer()));
+                server.broadcastEvent("suggestions_updated", data);
+            } catch (JSONException e) {
+                // JSON construction over constant keys can't fail.
+            }
+        }
+    }
+
+    // ---- Content ----
+
+    public static void openVideo(String url, String videoId, Long positionMs, String playlistId, Integer playlistIndex) {
+        final String resolvedId = (videoId == null && url != null) ? extractVideoIdFromUrl(url) : videoId;
+        // No explicit playlist id, but the url may carry one (?list=...) — resolve it.
+        final String resolvedPlaylistId = (playlistId == null || playlistId.isEmpty()) && url != null
+                ? extractPlaylistIdFromUrl(url) : playlistId;
+        runOnMainThread(() -> {
+            if (sPresenter == null) {
+                return;
+            }
+
+            if (resolvedId == null) {
+                return;
+            }
+
+            Video video = Video.from(resolvedId);
+
+            if (resolvedPlaylistId != null && !resolvedPlaylistId.isEmpty()) {
+                video.remotePlaylistId = resolvedPlaylistId;
+            }
+
+            if (playlistIndex != null) {
+                video.playlistIndex = playlistIndex;
+            }
+
+            if (positionMs != null) {
+                video.pendingPosMs = positionMs;
+            }
+
+            video.isRemote = true;
+            sPresenter.openVideo(video);
+        });
+    }
+
+    public static JSONArray getSuggestions() {
+        // SmartTube's own "Up Next": the player's loaded suggestion rows for the current video (populated
+        // by SuggestionsController.loadSuggestions() from cached metadata, in a stable order) — reliable
+        // and consistent across calls, no fresh network fetch.
+        JSONArray result = new JSONArray();
+        Set<String> seen = new HashSet<>();
+        Video current = Playlist.instance().getCurrent();
+
+        // Exclude the current video's OWN group. SuggestionsController.appendSectionPlaylistIfNeeded()
+        // adds that group as a suggestion row ("section playlist"); when the video was reached via
+        // autoplay/Home, that group IS the Home/recommended feed — the "Up Next mixed with home
+        // recommended" bug. Pre-seeding `seen` with the group's ids makes the loop skip them, leaving
+        // only the video's actual related suggestions.
+        if (current != null && current.getGroup() != null) {
+            VideoGroup ownGroup = current.getGroup();
+            if (ownGroup.getVideos() != null) {
+                for (Video v : ownGroup.getVideos()) {
+                    if (v.videoId != null) {
+                        seen.add(v.videoId);
+                    }
+                }
+            }
+        }
+
+        forEachSuggestion(getPlayer(), video -> {
+            if (video.videoId != null && seen.add(video.videoId)) {
+                try {
+                    result.put(videoToJson(video));
+                } catch (JSONException e) {
+                    // skip this video
+                }
+            }
+            return false;
+        });
+        return result;
+    }
+
+    /**
+     * Chapters of the currently playing video, as parsed from YouTube metadata by
+     * SuggestionsController. Read-only snapshot — safe to call from NanoHTTPD worker
+     * threads (same direct-read style as getSuggestions()); the chapter list field
+     * is volatile and ChapterItems are immutable once parsed. Returns [] when
+     * nothing is playing or the video has no chapters.
+     */
+    public static JSONArray getChapters() {
+        JSONArray result = new JSONArray();
+
+        if (sPresenter == null) {
+            return result;
+        }
+
+        SuggestionsController controller = sPresenter.getController(SuggestionsController.class);
+        if (controller == null) {
+            return result;
+        }
+
+        List<ChapterItem> chapters = controller.getChapters();
+        if (chapters == null || chapters.isEmpty()) {
+            return result;
+        }
+
+        // end_ms of each chapter = start of the next one; the last chapter ends at the
+        // video duration (when the player can tell us — otherwise omit the field).
+        PlaybackView player = getPlayer();
+        long durationMs = player != null ? player.getDurationMs() : 0;
+
+        for (int i = 0; i < chapters.size(); i++) {
+            ChapterItem chapter = chapters.get(i);
+            if (chapter == null) {
+                continue;
+            }
+            try {
+                JSONObject json = new JSONObject();
+                json.put("title", chapter.getTitle());
+                json.put("start_ms", chapter.getStartTimeMs());
+                if (i + 1 < chapters.size() && chapters.get(i + 1) != null) {
+                    json.put("end_ms", chapters.get(i + 1).getStartTimeMs());
+                } else if (durationMs > 0) {
+                    json.put("end_ms", durationMs);
+                }
+                String thumb = chapter.getCardImageUrl();
+                if (thumb != null && !thumb.isEmpty()) {
+                    json.put("thumbnail_url", thumb);
+                }
+                result.put(json);
+            } catch (JSONException e) {
+                // skip this chapter
+            }
+        }
+
+        return result;
+    }
+
+    // ---- Recommended feed (YouTube Home) ----
+
+    private static final Object sRecommendedLock = new Object();
+    private static JSONArray sRecommendedCache;
+    private static long sRecommendedCacheAt;
+    private static final long RECOMMENDED_TTL_MS = 5 * 60 * 1000;
+
+    /**
+     * The user's actual Home recommendations — unlike getSuggestions(), which returns
+     * the videos related to what's currently playing. Blocking network call; must be
+     * invoked from a worker thread (NanoHTTPD request threads are fine).
+     */
+    public static JSONArray getRecommended() {
+        synchronized (sRecommendedLock) {
+            if (sRecommendedCache != null && System.currentTimeMillis() - sRecommendedCacheAt < RECOMMENDED_TTL_MS) {
+                return sRecommendedCache;
+            }
+        }
+
+        JSONArray result = new JSONArray();
+        try {
+            MediaGroup group = YouTubeServiceManager.instance().getContentService().getRecommended();
+            if (group != null && group.getMediaItems() != null) {
+                for (MediaItem item : group.getMediaItems()) {
+                    if (item.getVideoId() == null) {
+                        continue;
+                    }
+                    result.put(mediaItemToJson(item));
+                }
+            }
+        } catch (Exception e) {
+            // Network/parse failure — return whatever we collected (possibly empty).
+        }
+
+        if (result.length() > 0) {
+            synchronized (sRecommendedLock) {
+                sRecommendedCache = result;
+                sRecommendedCacheAt = System.currentTimeMillis();
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Play a suggestion by video ID — robust against the list refreshing between
+     * the client fetching it and the user clicking (indexes go stale, IDs don't).
+     * Prefers the player's own suggestion Video object so playback keeps its
+     * metadata/context; falls back to opening the bare ID.
+     */
+    public static void playSuggestionById(String videoId) {
+        runOnMainThread(() -> {
+            if (videoId == null || sPresenter == null) {
+                return;
+            }
+
+            boolean[] found = {false};
+            forEachSuggestion(getPlayer(), video -> {
+                if (videoId.equals(video.videoId)) {
+                    video.pendingPosMs = 0;
+                    sPresenter.openVideo(video);
+                    found[0] = true;
+                    return true;
+                }
+                return false;
+            });
+
+            if (!found[0]) {
+                Video video = Video.from(videoId);
+                video.isRemote = true;
+                sPresenter.openVideo(video);
+            }
+        });
+    }
+
+    public static void playSuggestion(int index) {
+        withPlayerOnMain(player -> {
+            int[] currentIndex = {0};
+            forEachSuggestion(player, video -> {
+                if (currentIndex[0] == index) {
+                    video.pendingPosMs = 0;
+                    sPresenter.openVideo(video);
+                    return true;
+                }
+                currentIndex[0]++;
+                return false;
+            });
+        });
+    }
+
+    @FunctionalInterface
+    private interface SuggestionVisitor {
+        /** Return true to stop iterating. */
+        boolean visit(Video video);
+    }
+
+    // Walk every playable suggestion video across all groups for the given player,
+    // hiding the indexed-group scan and the null-group termination. No-op if player
+    // is null. Stops early once the visitor returns true.
+    private static void forEachSuggestion(PlaybackView player, SuggestionVisitor visitor) {
+        if (player == null) {
+            return;
+        }
+        for (int i = 0; i < MAX_SUGGESTION_GROUPS; i++) {
+            VideoGroup group = player.getSuggestionsByIndex(i);
+            if (group == null) {
+                break;
+            }
+            for (Video video : group.getVideos()) {
+                if (video.hasVideo() && visitor.visit(video)) {
+                    return;
+                }
+            }
+        }
+    }
+
+    // Total number of items across all suggestion groups (counts group sizes, not
+    // filtered by hasVideo — mirrors what the player's grid shows).
+    private static int countSuggestions(PlaybackView player) {
+        if (player == null) {
+            return 0;
+        }
+        int count = 0;
+        for (int i = 0; i < MAX_SUGGESTION_GROUPS; i++) {
+            VideoGroup group = player.getSuggestionsByIndex(i);
+            if (group == null) {
+                break;
+            }
+            count += group.getSize();
+        }
+        return count;
+    }
+
+    // ---- Subtitles ----
+
+    public static void toggleSubtitles() {
+        withPlayerOnMain(player -> player.showSubtitles(!isSubtitleButtonOn(player)));
+    }
+
+    /** Deterministically enable or disable subtitles (closed captions). */
+    public static void setSubtitlesEnabled(boolean enabled) {
+        withPlayerOnMain(player -> player.showSubtitles(enabled));
+    }
+
+    public static boolean areSubtitlesOn() {
+        PlaybackView player = getPlayer();
+        return player != null && isSubtitleButtonOn(player);
+    }
+
+    private static boolean isSubtitleButtonOn(PlaybackView player) {
+        return player.getButtonState(
+                com.liskovsoft.smartyoutubetv2.common.R.id.lb_control_closed_captioning)
+                == PlayerUI.BUTTON_ON;
+    }
+
+    // ---- Mute / Unmute ----
+
+    public static void toggleMute() {
+        withPlayerOnMain(player -> {
+            boolean isMuted = player.getVolume() == 0f;
+            if (isMuted && sPreviousVolume > 0f) {
+                player.setVolume(sPreviousVolume);
+            } else {
+                sPreviousVolume = player.getVolume();
+                player.setVolume(0f);
+            }
+        });
+    }
+
+    public static boolean isMuted() {
+        PlaybackView player = getPlayer();
+        return player != null && player.getVolume() == 0f;
+    }
+
+    // ---- Picture-in-Picture ----
+
+    /**
+     * Toggle Picture-in-Picture: enter if the player is in fullscreen, exit (back to
+     * fullscreen) if it's already in PIP. Entering mirrors PlayerUIController.onPipClicked();
+     * exiting unblocks the engine and brings the player view back to the foreground via
+     * ViewManager.movePlayerToForeground() — the app's own "surface the player" path,
+     * which expands it out of the PIP window.
+     */
+    public static void togglePip() {
+        withPlayerOnMain(player -> {
+            if (player.isInPIPMode()) {
+                player.blockEngine(false);
+                Context context = sPresenter.getContext();
+                if (context != null) {
+                    ViewManager.instance(context).movePlayerToForeground();
+                }
+            } else {
+                player.showOverlay(false);
+                player.blockEngine(true);
+                player.finish();
+            }
+        });
+    }
+
+    public static boolean isPipActive() {
+        PlaybackView player = getPlayer();
+        return player != null && player.isInPIPMode();
+    }
+
+    // ---- Search ----
+
+    public static void search(String query) {
+        runOnMainThread(() -> {
+            if (sPresenter == null || query == null || query.isEmpty()) {
+                return;
+            }
+
+            Context context = sPresenter.getContext();
+            if (context == null) {
+                return;
+            }
+
+            SearchPresenter.instance(context).startPlay(query);
+        });
+    }
+
+    /**
+     * Fetch YouTube search results WITHOUT starting playback — unlike search(),
+     * which plays the first hit. Blocking network call (same synchronous style
+     * as getRecommended()); must be invoked from a worker thread (NanoHTTPD
+     * request threads are fine). Items match the /api/content/suggestions shape.
+     */
+    public static JSONArray searchResults(String query, int limit) {
+        JSONArray result = new JSONArray();
+        if (query == null || query.isEmpty()) {
+            return result;
+        }
+
+        try {
+            List<MediaGroup> groups = YouTubeServiceManager.instance().getContentService().getSearch(query);
+            if (groups != null) {
+                for (MediaGroup group : groups) {
+                    if (group == null || group.getMediaItems() == null) {
+                        continue;
+                    }
+                    for (MediaItem item : group.getMediaItems()) {
+                        if (result.length() >= limit) {
+                            return result;
+                        }
+                        if (item.getVideoId() == null) {
+                            continue;
+                        }
+                        result.put(mediaItemToJson(item));
+                    }
+                }
+            }
+        } catch (Exception e) {
+            // Network/parse failure — return whatever we collected (possibly empty).
+        }
+
+        return result;
+    }
+
+    // ---- Queue Management ----
+
+    public static JSONArray getQueue() {
+        Playlist playlist = Playlist.instance();
+        List<Video> all = playlist.getAll();
+        Video current = playlist.getCurrent();
+
+        JSONArray result = new JSONArray();
+        for (int i = 0; i < all.size(); i++) {
+            Video video = all.get(i);
+            try {
+                JSONObject item = videoToJson(video);
+                item.put("index", i);
+                item.put("is_current", video.equals(current));
+                result.put(item);
+            } catch (JSONException e) {
+                // skip
+            }
+        }
+        return result;
+    }
+
+    public static void addToQueue(String videoId) {
+        runOnMainThread(() -> {
+            if (videoId == null) {
+                return;
+            }
+            Video video = Video.from(videoId);
+            video.isRemote = true;
+            Playlist.instance().add(video);
+        });
+    }
+
+    public static void playNext(String videoId) {
+        runOnMainThread(() -> {
+            if (videoId == null) {
+                return;
+            }
+            Video video = Video.from(videoId);
+            video.isRemote = true;
+            Playlist.instance().next(video);
+        });
+    }
+
+    public static void removeFromQueue(String videoId) {
+        runOnMainThread(() -> {
+            if (videoId == null) {
+                return;
+            }
+            Playlist playlist = Playlist.instance();
+            for (Video video : playlist.getAll()) {
+                if (videoId.equals(video.videoId)) {
+                    playlist.remove(video);
+                    break;
+                }
+            }
+        });
+    }
+
+    public static void clearQueue() {
+        runOnMainThread(() -> Playlist.instance().clear());
+    }
+
+    public static void shuffleQueue() {
+        runOnMainThread(() -> Playlist.instance().shuffle());
+    }
+
+    public static void moveQueueItem(int from, int to) {
+        runOnMainThread(() -> Playlist.instance().move(from, to));
+    }
+
+    /**
+     * Bulk-add a whole playlist to the queue. The playlist's items are fetched
+     * synchronously (blocking continuation paging like getRecommended()), so this
+     * MUST be called from a worker thread (NanoHTTPD request threads are fine).
+     * Only the final Playlist mutation + optional auto-start hops to the main thread.
+     */
+    public static void addPlaylistToQueue(String playlistId, boolean shuffle) {
+        if (playlistId == null || playlistId.isEmpty()) {
+            return;
+        }
+
+        final List<Video> videos = new ArrayList<>();
+        try {
+            MediaGroup playlistGroup = resolvePlaylistGroup(playlistId);
+            List<MediaItem> items = loadAllPlaylistItems(playlistGroup);
+            if (items != null) {
+                for (MediaItem item : items) {
+                    if (item.getVideoId() == null) {
+                        continue;
+                    }
+                    Video video = Video.from(item);
+                    video.isRemote = true;
+                    videos.add(video);
+                }
+            }
+        } catch (Exception e) {
+            // Network/parse failure — swallow and return (matches getRecommended()).
+            return;
+        }
+
+        if (videos.isEmpty()) {
+            return;
+        }
+
+        runOnMainThread(() -> {
+            Playlist playlist = Playlist.instance();
+            for (Video video : videos) {
+                playlist.add(video);
+            }
+            if (shuffle) {
+                playlist.shuffle();
+            }
+
+            // Nothing is playing yet — start the first item so the bulk add is audible.
+            PlaybackView player = getPlayer();
+            if (sPresenter != null && (player == null || !player.containsMedia())) {
+                Video current = playlist.getCurrent();
+                if (current != null) {
+                    current.isRemote = true;
+                    sPresenter.openVideo(current);
+                }
+            }
+        });
+    }
+
+    /**
+     * Resolve a playlist id to its MediaGroup. The playlist row is the first
+     * suggestion row in the playlist's metadata that actually has media items.
+     * Uses the blocking MediaItemService.getMetadata(...) overload to stay
+     * consistent with getRecommended()'s synchronous worker-thread style.
+     */
+    private static MediaGroup resolvePlaylistGroup(String playlistId) {
+        MediaItemMetadata metadata = YouTubeServiceManager.instance()
+                .getMediaItemService().getMetadata(null, playlistId, 0, null);
+        if (metadata == null || metadata.getSuggestions() == null) {
+            return null;
+        }
+        for (MediaGroup group : metadata.getSuggestions()) {
+            List<MediaItem> mediaItems = group.getMediaItems();
+            if (mediaItems != null && !mediaItems.isEmpty()) {
+                return group;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Page through a playlist's continuations (blocking) up to the configured caps,
+     * collecting all of its MediaItems.
+     */
+    private static List<MediaItem> loadAllPlaylistItems(MediaGroup playlistGroup) {
+        if (playlistGroup == null) {
+            return null;
+        }
+        List<MediaItem> allItems = new ArrayList<>();
+        List<MediaItem> firstItems = playlistGroup.getMediaItems();
+        if (firstItems != null) {
+            allItems.addAll(firstItems);
+        }
+        MediaGroup currentGroup = playlistGroup;
+        ContentService contentService = YouTubeServiceManager.instance().getContentService();
+        for (int i = 0; i < MAX_PLAYLIST_CONTINUATIONS && allItems.size() < MAX_TOTAL_PLAYLIST_ITEMS; i++) {
+            try {
+                String nextPageKey = currentGroup.getNextPageKey();
+                if (nextPageKey == null || nextPageKey.isEmpty()) {
+                    break;
+                }
+                MediaGroup nextGroup = contentService.continueGroup(currentGroup);
+                if (nextGroup == null || nextGroup.isEmpty()) {
+                    break;
+                }
+                List<MediaItem> nextItems = nextGroup.getMediaItems();
+                if (nextItems != null) {
+                    int remaining = MAX_TOTAL_PLAYLIST_ITEMS - allItems.size();
+                    if (nextItems.size() > remaining) {
+                        allItems.addAll(nextItems.subList(0, remaining));
+                        break;
+                    }
+                    allItems.addAll(nextItems);
+                }
+                currentGroup = nextGroup;
+            } catch (Exception e) {
+                break;
+            }
+        }
+        return allItems;
+    }
+
+    // ---- System Control ----
+
+    public static void dpad(String key) {
+        runOnMainThread(() -> {
+            int keyCode;
+
+            switch (key) {
+                case "up":
+                    keyCode = KeyEvent.KEYCODE_DPAD_UP;
+                    break;
+                case "down":
+                    keyCode = KeyEvent.KEYCODE_DPAD_DOWN;
+                    break;
+                case "left":
+                    keyCode = KeyEvent.KEYCODE_DPAD_LEFT;
+                    break;
+                case "right":
+                    keyCode = KeyEvent.KEYCODE_DPAD_RIGHT;
+                    break;
+                case "enter":
+                    keyCode = KeyEvent.KEYCODE_DPAD_CENTER;
+                    break;
+                case "back":
+                    keyCode = KeyEvent.KEYCODE_BACK;
+                    break;
+                default:
+                    return;
+            }
+
+            // Each press is a clean ACTION_DOWN + ACTION_UP. Focus navigation happens on the
+            // DOWN (see Utils.sendKey); the UP completes clicks for DPAD_CENTER/ENTER.
+            Utils.sendKey(keyCode);
+        });
+    }
+
+    public static void voice(String action) {
+        runOnMainThread(() -> {
+            if (sPresenter == null) {
+                return;
+            }
+
+            Context context = sPresenter.getContext();
+            if (context == null) {
+                return;
+            }
+
+            SearchPresenter searchPresenter = SearchPresenter.instance(context);
+
+            if ("start".equals(action)) {
+                searchPresenter.startVoice();
+            } else if ("stop".equals(action)) {
+                searchPresenter.forceFinish();
+            }
+        });
+    }
+
+    // ---- Helpers ----
+
+    // The fields shared by every video-list endpoint (suggestions, queue, player
+    // state). Callers add their own extras (index/is_current, channel_id, …).
+    private static JSONObject videoToJson(Video video) throws JSONException {
+        JSONObject json = new JSONObject();
+        json.put("video_id", video.videoId);
+        // Use getTitleFull(), not getTitle(): a video opened by bare id (search → play, remote
+        // API) has a null `title` field — only `metadataTitle` gets populated once metadata loads
+        // (author/channel/duration do too, which is why those show but the title was missing).
+        // getTitle() ignores metadataTitle; getTitleFull() falls back to it. Otherwise org.json
+        // drops the null and the client shows "untitled" / "no video loaded".
+        json.put("title", video.getTitleFull());
+        json.put("author", video.getAuthor());
+        json.put("thumbnail_url", bestThumbnail(video));
+        json.put("duration_ms", video.getDurationMs());
+        json.put("is_live", video.isLive);
+        return json;
+    }
+
+    // YouTube-API MediaItem → the same wire shape as videoToJson(), used by the
+    // recommended feed and search results. Author falls back to the second title.
+    private static JSONObject mediaItemToJson(MediaItem item) throws JSONException {
+        JSONObject json = new JSONObject();
+        json.put("video_id", item.getVideoId());
+        json.put("title", item.getTitle());
+        json.put("author", item.getAuthor() != null ? item.getAuthor()
+                : (item.getSecondTitle() != null ? item.getSecondTitle().toString() : null));
+        String thumb = item.getBackgroundImageUrl() != null
+                ? item.getBackgroundImageUrl() : item.getCardImageUrl();
+        json.put("thumbnail_url", thumb);
+        json.put("duration_ms", item.getDurationMs());
+        json.put("is_live", item.isLive());
+        return json;
+    }
+
+    private static JSONArray formatListToJson(List<FormatItem> formats) {
+        JSONArray array = new JSONArray();
+        if (formats == null) {
+            return array;
+        }
+
+        for (FormatItem format : formats) {
+            JSONObject json = formatToJsonObject(format);
+            if (json != null) {
+                array.put(json);
+            }
+        }
+
+        return array;
+    }
+
+    private static JSONObject formatToJsonObject(FormatItem format) {
+        if (format == null) {
+            return null;
+        }
+
+        try {
+            JSONObject json = new JSONObject();
+            json.put("format_id", format.getFormatId());
+            json.put("width", format.getWidth());
+            json.put("height", format.getHeight());
+            json.put("frame_rate", format.getFrameRate());
+            json.put("label", format.getTitle() != null ? format.getTitle().toString() : "");
+            json.put("is_selected", format.isSelected());
+
+            MediaTrack track = format.getTrack();
+            if (track != null && track.format != null) {
+                json.put("codec", TrackSelectorUtil.extractCodec(track.format));
+                json.put("bitrate", track.format.bitrate);
+            }
+
+            json.put("language", format.getLanguage() != null ? format.getLanguage() : "");
+
+            return json;
+        } catch (JSONException e) {
+            return null;
+        }
+    }
+
+    private static FormatItem findFormatById(List<FormatItem> formats, String formatId) {
+        if (formats == null || formatId == null) {
+            return null;
+        }
+
+        for (FormatItem item : formats) {
+            if (formatId.equals(item.getFormatId())) {
+                return item;
+            }
+        }
+
+        return null;
+    }
+
+    private static String extractVideoIdFromUrl(String url) {
+        if (url == null || url.isEmpty()) {
+            return null;
+        }
+
+        Uri uri;
+        try {
+            uri = Uri.parse(url);
+        } catch (Exception e) {
+            return null;
+        }
+
+        if (uri == null) {
+            return null;
+        }
+
+        String videoId = uri.getQueryParameter("v");
+
+        if (videoId == null) {
+            String host = uri.getHost();
+            if (host != null && (host.contains("youtu.be") || host.contains("youtube-nocookie.com"))) {
+                videoId = uri.getLastPathSegment();
+            }
+        }
+
+        if (videoId == null) {
+            String path = uri.getPath();
+            if (path != null && path.contains("/embed/")) {
+                int embedIdx = path.indexOf("/embed/") + "/embed/".length();
+                if (embedIdx < path.length()) {
+                    videoId = path.substring(embedIdx);
+                    int slashIdx = videoId.indexOf('/');
+                    if (slashIdx > 0) {
+                        videoId = videoId.substring(0, slashIdx);
+                    }
+                }
+            }
+        }
+
+        if (videoId == null) {
+            videoId = uri.getLastPathSegment();
+        }
+
+        if (videoId != null && videoId.length() == 11) {
+            return videoId;
+        }
+
+        return null;
+    }
+
+    static String extractPlaylistIdFromUrl(String url) {
+        if (url == null || url.isEmpty()) {
+            return null;
+        }
+
+        Uri uri;
+        try {
+            uri = Uri.parse(url);
+        } catch (Exception e) {
+            return null;
+        }
+
+        if (uri == null) {
+            return null;
+        }
+
+        String playlistId = uri.getQueryParameter("list");
+        if (playlistId == null || playlistId.isEmpty()) {
+            return null;
+        }
+        return playlistId;
+    }
+}
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/RemoteApiConstants.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/RemoteApiConstants.java
new file mode 100644
index 0000000000..42b67ffa29
--- /dev/null
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/RemoteApiConstants.java
@@ -0,0 +1,16 @@
+package com.liskovsoft.smartyoutubetv2.common.misc.remoteapi;
+
+/**
+ * Constants shared across the remote control API (server, prefs, auth).
+ * Single source of truth so the default port / protocol version can't drift
+ * between {@link RemoteApiServer} and {@link com.liskovsoft.smartyoutubetv2.common.prefs.RemoteApiData}.
+ */
+public final class RemoteApiConstants {
+    private RemoteApiConstants() {}
+
+    /** Default TCP (HTTP/WebSocket) and UDP (discovery) port for the remote API server. */
+    public static final int DEFAULT_PORT = 8497;
+
+    /** Wire protocol version reported via UDP discovery, GET /api/system/ping and the WS hello. */
+    public static final String API_VERSION = "1";
+}
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/RemoteApiServer.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/RemoteApiServer.java
new file mode 100644
index 0000000000..5200ce6e2a
--- /dev/null
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/remoteapi/RemoteApiServer.java
@@ -0,0 +1,1072 @@
+package com.liskovsoft.smartyoutubetv2.common.misc.remoteapi;
+
+import android.content.Context;
+import android.os.Build;
+
+import com.liskovsoft.sharedutils.mylogger.Log;
+import com.liskovsoft.smartyoutubetv2.common.prefs.RemoteApiData;
+
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+import java.io.IOException;
+import java.net.DatagramPacket;
+import java.net.DatagramSocket;
+import java.net.InetAddress;
+import java.util.HashMap;
+import java.util.Map;
+
+import java.util.concurrent.CopyOnWriteArrayList;
+
+import fi.iki.elonen.NanoHTTPD;
+import fi.iki.elonen.NanoHTTPD.ResponseException;
+import fi.iki.elonen.NanoWSD;
+import fi.iki.elonen.NanoWSD.WebSocket;
+import fi.iki.elonen.NanoWSD.WebSocketFrame;
+
+public class RemoteApiServer extends NanoWSD {
+    private static final String TAG = RemoteApiServer.class.getSimpleName();
+    private static final String API_VERSION = RemoteApiConstants.API_VERSION;
+
+    private static RemoteApiServer sInstance;
+
+    private final RemoteApiAuthProvider mAuth;
+    private final RemoteApiData mApiData;
+    private final Context mContext;
+    // Cached once: querying Build.MODEL / PackageManager on every request is wasteful.
+    private final String mDeviceName;
+    private final String mAppVersion;
+    private Thread mUdpThread;
+    private volatile DatagramSocket mUdpSocket;
+    private volatile boolean mRunning;
+    private final CopyOnWriteArrayList<RemoteApiWebSocket> mWebSocketClients = new CopyOnWriteArrayList<>();
+    private Thread mBroadcastThread;
+
+    // Routes reachable without a token (discovery + pairing). Everything else goes
+    // through the auth gate before its handler runs.
+    private final Map<String, RouteHandler> mPublicRoutes = new HashMap<>();
+    private final Map<String, RouteHandler> mRoutes = new HashMap<>();
+
+    @FunctionalInterface
+    private interface RouteHandler {
+        Response handle(IHTTPSession session) throws JSONException, IOException;
+    }
+
+    public RemoteApiServer(Context context, RemoteApiData apiData) {
+        this(context, apiData.getPort(), apiData);
+    }
+
+    public RemoteApiServer(Context context, int port, RemoteApiData apiData) {
+        super(port);
+        mContext = context.getApplicationContext();
+        mApiData = apiData;
+        mAuth = new RemoteApiAuthProvider(apiData);
+        mDeviceName = resolveDeviceName();
+        mAppVersion = resolveAppVersion();
+        registerRoutes();
+    }
+
+    public static synchronized void startRemoteApi(Context context) {
+        if (sInstance != null && sInstance.isAlive()) {
+            return;
+        }
+        RemoteApiData data = RemoteApiData.instance(context);
+        if (!data.isApiEnabled()) {
+            return;
+        }
+        try {
+            sInstance = new RemoteApiServer(context, data);
+            sInstance.start();
+        } catch (IOException e) {
+            Log.e(TAG, "Failed to start Remote API server: %s", e.getMessage());
+        }
+    }
+
+    public static synchronized void stopRemoteApi(Context context) {
+        if (sInstance != null) {
+            sInstance.stop();
+            sInstance = null;
+        }
+    }
+
+    public static synchronized RemoteApiServer getInstance() {
+        return sInstance;
+    }
+
+    public static void pushEvent(String eventType, JSONObject data) {
+        RemoteApiServer server = sInstance;
+        if (server != null) {
+            server.broadcastEvent(eventType, data);
+        }
+    }
+
+    @Override
+    public void start() throws IOException {
+        mRunning = true;
+        super.start();
+        startUdpListener();
+        startBroadcastLoop();
+        Log.i(TAG, "Remote API server started on port %d", getListeningPort());
+    }
+
+    @Override
+    public void stop() {
+        mRunning = false;
+        // Close the UDP socket first: socket.receive() is a blocking call that interrupt() can't wake,
+        // so closing the socket is what actually unblocks the listener thread and lets it exit.
+        DatagramSocket udpSocket = mUdpSocket;
+        if (udpSocket != null && !udpSocket.isClosed()) {
+            udpSocket.close();
+        }
+        if (mUdpThread != null) {
+            mUdpThread.interrupt();
+            mUdpThread = null;
+        }
+        if (mBroadcastThread != null) {
+            mBroadcastThread.interrupt();
+            mBroadcastThread = null;
+        }
+        for (RemoteApiWebSocket ws : mWebSocketClients) {
+            try { ws.close(WebSocketFrame.CloseCode.NormalClosure, "server shutting down", false); } catch (Exception ignored) {}
+        }
+        mWebSocketClients.clear();
+        try {
+            super.stop();
+        } catch (Exception e) {
+            Log.e(TAG, "Error stopping HTTP server: %s", e.getMessage());
+        }
+        Log.i(TAG, "Remote API server stopped");
+    }
+
+    private void startUdpListener() {
+        mUdpThread = new Thread(() -> {
+            DatagramSocket socket = null;
+            try {
+                socket = new DatagramSocket(getListeningPort());
+                mUdpSocket = socket;
+                socket.setBroadcast(true);
+                byte[] buffer = new byte[1024];
+
+                while (mRunning && !Thread.currentThread().isInterrupted()) {
+                    DatagramPacket packet = new DatagramPacket(buffer, buffer.length);
+                    try {
+                        socket.receive(packet);
+                        String message = new String(packet.getData(), 0, packet.getLength()).trim();
+                        handleUdpPacket(socket, packet, message);
+                    } catch (IOException e) {
+                        if (mRunning) {
+                            Log.e(TAG, "UDP receive error: %s", e.getMessage());
+                        }
+                    }
+                }
+            } catch (Exception e) {
+                if (mRunning) {
+                    Log.e(TAG, "UDP listener error: %s", e.getMessage());
+                }
+            } finally {
+                if (socket != null && !socket.isClosed()) {
+                    socket.close();
+                }
+            }
+        }, "RemoteApi-UdpListener");
+        mUdpThread.setDaemon(true);
+        mUdpThread.start();
+    }
+
+    private void handleUdpPacket(DatagramSocket socket, DatagramPacket incoming, String message) {
+        try {
+            JSONObject request = new JSONObject(message);
+            if ("discover".equals(request.optString("action"))) {
+                JSONObject response = new JSONObject();
+                response.put("device_name", getDeviceName());
+                response.put("device_id", getDeviceId());
+                response.put("api_port", getListeningPort());
+                response.put("app_version", getAppVersion());
+                response.put("api_version", API_VERSION);
+
+                byte[] responseBytes = response.toString().getBytes();
+                InetAddress senderAddress = incoming.getAddress();
+                DatagramPacket responsePacket = new DatagramPacket(
+                        responseBytes, responseBytes.length, senderAddress, incoming.getPort());
+                socket.send(responsePacket);
+                Log.d(TAG, "UDP discovery response sent to %s:%d", senderAddress.getHostAddress(), incoming.getPort());
+            }
+        } catch (JSONException e) {
+            Log.e(TAG, "Invalid UDP JSON: %s", e.getMessage());
+        } catch (IOException e) {
+            Log.e(TAG, "UDP send error: %s", e.getMessage());
+        }
+    }
+
+
+
+    // ---- WebSocket Support ----
+
+    @Override
+    protected WebSocket openWebSocket(NanoHTTPD.IHTTPSession handshake) {
+        String uri = handshake.getUri();
+        if (!"/ws".equals(uri)) {
+            return null;
+        }
+
+        Map<String, String> parms = handshake.getParms();
+        String token = parms.get("token");
+        if (!mApiData.isAllowAllConnections() && (token == null || !mAuth.isTokenValid(token))) {
+            Log.w(TAG, "WebSocket connection rejected: invalid or missing token");
+            return null;
+        }
+
+        RemoteApiWebSocket ws = new RemoteApiWebSocket(handshake);
+        mWebSocketClients.add(ws);
+        Log.i(TAG, "WebSocket client connected (%d total)", mWebSocketClients.size());
+        return ws;
+    }
+
+    private void startBroadcastLoop() {
+        mBroadcastThread = new Thread(() -> {
+            int tick = 0;
+            while (mRunning && !Thread.currentThread().isInterrupted()) {
+                try {
+                    Thread.sleep(500);
+                    broadcastState();
+                    // NanoHTTPD kills sockets after ~5s without a read. Browser JS can't
+                    // send WS pings, so the SERVER must ping; the client's auto-pong
+                    // resets the read timeout on both ends.
+                    if (++tick % 6 == 0) {
+                        pingClients();
+                    }
+                } catch (InterruptedException e) {
+                    break;
+                } catch (Exception e) {
+                    Log.e(TAG, "Broadcast error: %s", e.getMessage());
+                }
+            }
+        }, "RemoteApi-WsBroadcast");
+        mBroadcastThread.setDaemon(true);
+        mBroadcastThread.start();
+    }
+
+    @FunctionalInterface
+    private interface ClientSender {
+        void send(RemoteApiWebSocket ws) throws Exception;
+    }
+
+    // Single place that walks the client list, prunes anything closed, and drops a
+    // client if the send throws. broadcast/ping all funnel through here so the
+    // liveness bookkeeping can't drift between them.
+    private void forEachOpenClient(ClientSender sender) {
+        for (RemoteApiWebSocket ws : mWebSocketClients) {
+            if (!ws.isOpen()) {
+                mWebSocketClients.remove(ws);
+                continue;
+            }
+            try {
+                sender.send(ws);
+            } catch (Exception e) {
+                mWebSocketClients.remove(ws);
+            }
+        }
+    }
+
+    private void pingClients() {
+        byte[] payload = new byte[]{'k', 'a'};
+        forEachOpenClient(ws -> ws.ping(payload));
+    }
+
+    private void broadcastState() {
+        if (mWebSocketClients.isEmpty()) {
+            return;
+        }
+        JSONObject state = RemoteApiBridge.getPlayerState();
+        if (state == null) {
+            return;
+        }
+        sendEnvelope("state_update", state);
+    }
+
+    public void broadcastEvent(String eventType, JSONObject data) {
+        if (mWebSocketClients.isEmpty()) {
+            return;
+        }
+        sendEnvelope(eventType, data);
+    }
+
+    // Wrap data in the {type, data} envelope and fan it out to every open client.
+    private void sendEnvelope(String type, JSONObject data) {
+        JSONObject msg = new JSONObject();
+        try {
+            msg.put("type", type);
+            msg.put("data", data);
+        } catch (JSONException e) {
+            return;
+        }
+        String payload = msg.toString();
+        forEachOpenClient(ws -> ws.send(payload));
+    }
+
+    private class RemoteApiWebSocket extends WebSocket {
+        RemoteApiWebSocket(NanoHTTPD.IHTTPSession handshake) {
+            super(handshake);
+        }
+
+        @Override
+        protected void onOpen() {
+            Log.d(TAG, "WebSocket opened");
+            try {
+                JSONObject hello = new JSONObject();
+                hello.put("type", "hello");
+                hello.put("api_version", API_VERSION);
+                hello.put("device_name", getDeviceName());
+                send(hello.toString());
+            } catch (Exception e) {
+                Log.e(TAG, "WebSocket hello error: %s", e.getMessage());
+            }
+        }
+
+        @Override
+        protected void onClose(WebSocketFrame.CloseCode code, String reason, boolean initiatedByRemote) {
+            mWebSocketClients.remove(this);
+            Log.d(TAG, "WebSocket closed: %s (%d remaining)", reason, mWebSocketClients.size());
+        }
+
+        @Override
+        protected void onMessage(WebSocketFrame message) {
+            String text = message.getTextPayload();
+            try {
+                JSONObject cmd = new JSONObject(text);
+                String action = cmd.optString("action");
+                handleWebSocketCommand(action, cmd);
+            } catch (JSONException e) {
+                Log.e(TAG, "Invalid WebSocket message: %s", e.getMessage());
+            }
+        }
+
+        @Override
+        protected void onPong(WebSocketFrame pong) {}
+
+        @Override
+        protected void onException(IOException exception) {
+            Log.e(TAG, "WebSocket exception: %s", exception.getMessage());
+            mWebSocketClients.remove(this);
+        }
+
+        // Send a {type, data} response to this single client.
+        private void sendResponse(String type, Object data) {
+            try {
+                JSONObject resp = new JSONObject();
+                resp.put("type", type);
+                resp.put("data", data);
+                send(resp.toString());
+            } catch (Exception e) {
+                Log.e(TAG, "WebSocket %s response error: %s", type, e.getMessage());
+            }
+        }
+
+        private void handleWebSocketCommand(String action, JSONObject cmd) {
+            switch (action) {
+                case "play":
+                    RemoteApiBridge.handlePlay();
+                    break;
+                case "pause":
+                    RemoteApiBridge.handlePause();
+                    break;
+                case "toggle":
+                    RemoteApiBridge.handleToggle();
+                    break;
+                case "seek":
+                    long pos = cmd.optLong("position_ms", 0);
+                    RemoteApiBridge.handleSeek(pos);
+                    break;
+                case "next":
+                    RemoteApiBridge.handleNext();
+                    break;
+                case "previous":
+                    RemoteApiBridge.handlePrevious();
+                    break;
+                case "stop":
+                    RemoteApiBridge.handleStop();
+                    break;
+                case "reload":
+                    RemoteApiBridge.handleReload();
+                    break;
+                case "set_speed":
+                    float speed = (float) cmd.optDouble("speed", 1.0);
+                    RemoteApiBridge.setSpeed(speed);
+                    break;
+                case "set_volume":
+                    float vol = (float) cmd.optDouble("volume", 1.0);
+                    RemoteApiBridge.setVolume(vol);
+                    break;
+                case "set_video_format":
+                    RemoteApiBridge.setVideoFormat(cmd.optString("format_id"));
+                    break;
+                case "set_audio_format":
+                    RemoteApiBridge.setAudioFormat(cmd.optString("format_id"));
+                    break;
+                case "set_subtitle_format":
+                    RemoteApiBridge.setSubtitleFormat(cmd.optString("format_id"));
+                    break;
+                case "toggle_subtitles":
+                    RemoteApiBridge.toggleSubtitles();
+                    break;
+                case "toggle_mute":
+                    RemoteApiBridge.toggleMute();
+                    break;
+                case "search":
+                    RemoteApiBridge.search(cmd.optString("query"));
+                    break;
+                case "add_to_queue":
+                    RemoteApiBridge.addToQueue(cmd.optString("video_id"));
+                    break;
+                case "play_next":
+                    RemoteApiBridge.playNext(cmd.optString("video_id"));
+                    break;
+                case "remove_from_queue":
+                    RemoteApiBridge.removeFromQueue(cmd.optString("video_id"));
+                    break;
+                case "clear_queue":
+                    RemoteApiBridge.clearQueue();
+                    break;
+                case "shuffle_queue":
+                    RemoteApiBridge.shuffleQueue();
+                    break;
+                case "move_queue_item":
+                    if (cmd.has("from") && cmd.has("to")) {
+                        RemoteApiBridge.moveQueueItem(cmd.optInt("from"), cmd.optInt("to"));
+                    }
+                    break;
+                case "queue_playlist": {
+                    String playlistId = cmd.optString("playlist_id", null);
+                    if (playlistId == null || playlistId.isEmpty()) {
+                        playlistId = RemoteApiBridge.extractPlaylistIdFromUrl(cmd.optString("playlist_url", null));
+                    }
+                    if (playlistId != null && !playlistId.isEmpty()) {
+                        RemoteApiBridge.addPlaylistToQueue(playlistId, cmd.optBoolean("shuffle", false));
+                    }
+                    break;
+                }
+                case "toggle_pip":
+                    RemoteApiBridge.togglePip();
+                    break;
+                case "get_queue":
+                    sendResponse("queue_update", RemoteApiBridge.getQueue());
+                    break;
+                case "theater_power_toggle":
+                    getTheater().togglePower();
+                    break;
+                case "theater_get_state":
+                    sendResponse("theater_state", getTheater().getState());
+                    break;
+                case "get_state":
+                    JSONObject state = RemoteApiBridge.getPlayerState();
+                    if (state != null) {
+                        sendResponse("state_update", state);
+                    }
+                    break;
+            }
+        }
+    }
+
+    // ---- HTTP routing ----
+
+    // Register a route under the auth gate. Key is "METHOD /path".
+    private void route(Method method, String path, RouteHandler handler) {
+        mRoutes.put(method.name() + " " + path, handler);
+    }
+
+    // Register a fire-and-forget action that just returns {"ok": true}.
+    private void action(Method method, String path, Runnable action) {
+        route(method, path, session -> handleTransportAction(action));
+    }
+
+    private void registerRoutes() {
+        // ---- Public (no token required) ----
+        mPublicRoutes.put("GET /api/system/ping", session -> handlePing());
+        mPublicRoutes.put("GET /api/pair", session -> handlePair());
+        mPublicRoutes.put("POST /api/pair/verify", this::handlePairVerify);
+
+        // ---- Player state + transport ----
+        route(Method.GET, "/api/player", session -> handleGetPlayerState());
+        action(Method.POST, "/api/player/play", RemoteApiBridge::handlePlay);
+        action(Method.POST, "/api/player/pause", RemoteApiBridge::handlePause);
+        action(Method.POST, "/api/player/toggle", RemoteApiBridge::handleToggle);
+        route(Method.POST, "/api/player/seek", this::handleSeek);
+        action(Method.POST, "/api/player/next", RemoteApiBridge::handleNext);
+        action(Method.POST, "/api/player/previous", RemoteApiBridge::handlePrevious);
+        action(Method.POST, "/api/player/stop", RemoteApiBridge::handleStop);
+        action(Method.POST, "/api/player/reload", RemoteApiBridge::handleReload);
+
+        // ---- Playback settings ----
+        route(Method.GET, "/api/player/speed", session -> handleGetFloat("speed", RemoteApiBridge.getSpeed()));
+        route(Method.PUT, "/api/player/speed", session -> handleSetFloat(session, "speed", RemoteApiBridge::setSpeed));
+        route(Method.GET, "/api/player/volume", session -> handleGetFloat("volume", RemoteApiBridge.getVolume()));
+        route(Method.PUT, "/api/player/volume", session -> handleSetFloat(session, "volume", RemoteApiBridge::setVolume));
+        route(Method.GET, "/api/player/pitch", session -> handleGetFloat("pitch", RemoteApiBridge.getPitch()));
+        route(Method.PUT, "/api/player/pitch", session -> handleSetFloat(session, "pitch", RemoteApiBridge::setPitch));
+        route(Method.GET, "/api/player/chapters", session -> handleGetChapters());
+
+        // ---- Tracks ----
+        route(Method.GET, "/api/player/formats/video", session -> handleGetFormats(RemoteApiBridge.getVideoFormats()));
+        route(Method.GET, "/api/player/formats/audio", session -> handleGetFormats(RemoteApiBridge.getAudioFormats()));
+        route(Method.GET, "/api/player/formats/subtitle", session -> handleGetFormats(RemoteApiBridge.getSubtitleFormats()));
+        route(Method.GET, "/api/player/formats/selected", session -> handleGetSelectedTracks());
+        route(Method.PUT, "/api/player/formats/video", session -> handleSetFormat(session, RemoteApiBridge::setVideoFormat));
+        route(Method.PUT, "/api/player/formats/audio", session -> handleSetFormat(session, RemoteApiBridge::setAudioFormat));
+        route(Method.PUT, "/api/player/formats/subtitle", session -> handleSetFormat(session, RemoteApiBridge::setSubtitleFormat));
+
+        // ---- Video transform ----
+        route(Method.GET, "/api/player/video/resize", session -> handleGetInt("resize_mode", RemoteApiBridge.getResizeMode()));
+        route(Method.PUT, "/api/player/video/resize", session -> handleSetInt(session, "mode", RemoteApiBridge::setResizeMode));
+        route(Method.GET, "/api/player/video/zoom", session -> handleGetInt("zoom_percents", RemoteApiBridge.getZoom()));
+        route(Method.PUT, "/api/player/video/zoom", session -> handleSetInt(session, "zoom", RemoteApiBridge::setZoom));
+        route(Method.GET, "/api/player/video/rotation", session -> handleGetInt("rotation_angle", RemoteApiBridge.getRotation()));
+        route(Method.PUT, "/api/player/video/rotation", session -> handleSetInt(session, "angle", RemoteApiBridge::setRotation));
+        route(Method.GET, "/api/player/video/flip", session -> handleGetBool("flip_enabled", RemoteApiBridge.getFlip()));
+        route(Method.PUT, "/api/player/video/flip", session -> handleSetBool(session, "enabled", RemoteApiBridge::setFlip));
+
+        // ---- Subtitles (closed captions) ----
+        route(Method.POST, "/api/player/subtitle/toggle", session -> handleTransportAction(RemoteApiBridge::toggleSubtitles));
+        route(Method.PUT, "/api/player/subtitle", session -> handleSetBool(session, "enabled", RemoteApiBridge::setSubtitlesEnabled));
+        route(Method.GET, "/api/player/subtitle", session -> handleGetBool("enabled", RemoteApiBridge.areSubtitlesOn()));
+
+        // ---- Mute ----
+        action(Method.POST, "/api/player/mute/toggle", RemoteApiBridge::toggleMute);
+        route(Method.GET, "/api/player/mute", session -> handleGetBool("muted", RemoteApiBridge.isMuted()));
+
+        // ---- Picture-in-Picture ----
+        route(Method.GET, "/api/player/pip", session -> handleGetBool("active", RemoteApiBridge.isPipActive()));
+        action(Method.POST, "/api/player/pip/toggle", RemoteApiBridge::togglePip);
+        action(Method.POST, "/api/player/pip", RemoteApiBridge::togglePip); // back-compat alias
+
+        // ---- Content ----
+        route(Method.POST, "/api/content/search", session -> handleSetString(session, "query", RemoteApiBridge::search));
+        route(Method.GET, "/api/content/search/results", this::handleSearchResults);
+        route(Method.POST, "/api/content/open", this::handleContentOpen);
+        route(Method.GET, "/api/content/suggestions", session -> handleGetSuggestions());
+        route(Method.GET, "/api/content/recommended", session -> handleGetRecommended());
+
+        // ---- Queue ----
+        route(Method.GET, "/api/player/queue", session -> handleGetQueue());
+        route(Method.POST, "/api/player/queue", session -> handleSetString(session, "video_id", RemoteApiBridge::addToQueue));
+        route(Method.POST, "/api/player/queue/next", session -> handleSetString(session, "video_id", RemoteApiBridge::playNext));
+        route(Method.DELETE, "/api/player/queue", session -> handleSetString(session, "video_id", RemoteApiBridge::removeFromQueue));
+        action(Method.POST, "/api/player/queue/clear", RemoteApiBridge::clearQueue);
+        action(Method.POST, "/api/player/queue/shuffle", RemoteApiBridge::shuffleQueue);
+        route(Method.POST, "/api/player/queue/move", this::handleMoveQueueItem);
+        route(Method.POST, "/api/player/queue/playlist", this::handleQueuePlaylist);
+
+        // ---- Home Theater ----
+        route(Method.GET, "/api/theater", session -> handleGetTheaterState());
+        route(Method.GET, "/api/theater/volume", session -> handleGetTheaterVolume());
+        route(Method.PUT, "/api/theater/volume", this::handleSetTheaterVolume);
+        action(Method.POST, "/api/theater/volume/up", () -> getTheater().volumeUp());
+        action(Method.POST, "/api/theater/volume/down", () -> getTheater().volumeDown());
+        action(Method.POST, "/api/theater/mute/toggle", () -> getTheater().toggleMute());
+        action(Method.POST, "/api/theater/power/toggle", () -> getTheater().togglePower());
+        route(Method.GET, "/api/theater/refresh", session -> handleGetTheaterState());
+
+        // ---- System ----
+        route(Method.GET, "/api/system/dpad", this::handleDpad);
+        route(Method.POST, "/api/system/voice", this::handleVoice);
+    }
+
+    @Override
+    public Response serve(IHTTPSession session) {
+        if (isWebsocketRequested(session)) {
+            return super.serve(session);
+        }
+
+        String uri = session.getUri();
+        Method method = session.getMethod();
+        Map<String, String> headers = session.getHeaders();
+
+        if (Method.OPTIONS.equals(method)) {
+            return corsResponse(newFixedLengthResponse(Response.Status.OK, "application/json", "{}"));
+        }
+
+        String path = uri.endsWith("/") && uri.length() > 1 ? uri.substring(0, uri.length() - 1) : uri;
+        String key = method.name() + " " + path;
+
+        try {
+            RouteHandler publicRoute = mPublicRoutes.get(key);
+            if (publicRoute != null) {
+                return publicRoute.handle(session);
+            }
+
+            // When "allow all connections" is on, the LAN is trusted and no token is required.
+            if (!mApiData.isAllowAllConnections()) {
+                String token = extractBearerToken(headers.get("authorization"));
+                if (!mAuth.isTokenValid(token)) {
+                    return errorResponse(Response.Status.UNAUTHORIZED, 401, "Unauthorized");
+                }
+            }
+
+            RouteHandler route = mRoutes.get(key);
+            if (route != null) {
+                return route.handle(session);
+            }
+
+            // Dynamic: play a suggestion by index or video id.
+            if (Method.POST.equals(method) && path.startsWith("/api/content/suggestions/")) {
+                return handlePlaySuggestion(path.substring("/api/content/suggestions/".length()));
+            }
+
+            return errorResponse(Response.Status.NOT_FOUND, 404, "Not found");
+
+        } catch (JSONException e) {
+            Log.e(TAG, "JSON parse error: %s", e.getMessage());
+            return errorResponse(Response.Status.BAD_REQUEST, 400, "Invalid JSON");
+        } catch (Exception e) {
+            Log.e(TAG, "Request error: %s", e.getMessage());
+            return errorResponse(Response.Status.INTERNAL_ERROR, 503, "Internal error");
+        }
+    }
+
+    private Response handlePing() throws JSONException {
+        JSONObject body = new JSONObject();
+        body.put("status", "ok");
+        body.put("device_name", getDeviceName());
+        body.put("app_version", getAppVersion());
+        body.put("api_version", API_VERSION);
+        // Lets clients skip the pairing flow when the API is open on the LAN.
+        body.put("pairing_required", !mApiData.isAllowAllConnections());
+        return corsResponse(jsonResponse(body));
+    }
+
+    private Response handlePair() throws JSONException {
+        String code = mAuth.generatePairingCode();
+        JSONObject body = new JSONObject();
+        body.put("code", code);
+        body.put("expires_in", 300);
+        return corsResponse(jsonResponse(body));
+    }
+
+    private Response handlePairVerify(IHTTPSession session) throws JSONException, IOException {
+        JSONObject reqBody = parseBody(session);
+        String code = reqBody.getString("code");
+        String clientIp = session.getRemoteIpAddress();
+
+        if (mAuth.isRateLimited(clientIp)) {
+            return errorResponse(Response.Status.TOO_MANY_REQUESTS, 429, "Too many attempts, try again later");
+        }
+
+        String token = mAuth.verifyPairingCode(code, clientIp);
+        if (token == null) {
+            return errorResponse(Response.Status.UNAUTHORIZED, 401, "Invalid pairing code");
+        }
+
+        JSONObject body = new JSONObject();
+        body.put("token", token);
+        body.put("device_name", getDeviceName());
+        return corsResponse(jsonResponse(body));
+    }
+
+    private Response handleGetPlayerState() throws JSONException {
+        JSONObject state = RemoteApiBridge.getPlayerState();
+        if (state == null) {
+            return errorResponse(Response.Status.SERVICE_UNAVAILABLE, 503, "Player not available");
+        }
+        return corsResponse(jsonResponse(state));
+    }
+
+    private Response handleTransportAction(Runnable action) throws JSONException {
+        action.run();
+        return okResponse();
+    }
+
+    private Response handleSeek(IHTTPSession session) throws JSONException, IOException {
+        JSONObject reqBody = parseBody(session);
+        long positionMs = reqBody.getLong("position_ms");
+
+        JSONObject result = RemoteApiBridge.handleSeek(positionMs);
+        JSONObject body = new JSONObject();
+        body.put("ok", true);
+        if (result != null && result.has("position_ms")) {
+            body.put("position_ms", result.getLong("position_ms"));
+        } else {
+            body.put("position_ms", positionMs);
+        }
+        return corsResponse(jsonResponse(body));
+    }
+
+    private Response handleGetFloat(String key, float value) throws JSONException {
+        JSONObject body = new JSONObject();
+        body.put(key, value);
+        return corsResponse(jsonResponse(body));
+    }
+
+    private Response handleSetFloat(IHTTPSession session, String key, FloatSetter setter) throws JSONException, IOException {
+        JSONObject reqBody = parseBody(session);
+        float value = (float) reqBody.getDouble(key);
+        if (Float.isNaN(value) || Float.isInfinite(value)) {
+            return errorResponse(Response.Status.BAD_REQUEST, 400, "Invalid value for " + key);
+        }
+        setter.set(value);
+        return okResponse();
+    }
+
+    private Response handleGetInt(String key, int value) throws JSONException {
+        JSONObject body = new JSONObject();
+        body.put(key, value);
+        return corsResponse(jsonResponse(body));
+    }
+
+    private Response handleSetInt(IHTTPSession session, String key, IntSetter setter) throws JSONException, IOException {
+        JSONObject reqBody = parseBody(session);
+        int value = reqBody.getInt(key);
+        setter.set(value);
+        return okResponse();
+    }
+
+    private Response handleGetBool(String key, boolean value) throws JSONException {
+        JSONObject body = new JSONObject();
+        body.put(key, value);
+        return corsResponse(jsonResponse(body));
+    }
+
+    private Response handleSetBool(IHTTPSession session, String key, BoolSetter setter) throws JSONException, IOException {
+        JSONObject reqBody = parseBody(session);
+        boolean value = reqBody.getBoolean(key);
+        setter.set(value);
+        return okResponse();
+    }
+
+    private Response handleGetChapters() throws JSONException {
+        return corsResponse(jsonResponse(orEmptyArray(RemoteApiBridge.getChapters())));
+    }
+
+    private Response handleGetFormats(JSONArray formats) throws JSONException {
+        return corsResponse(jsonResponse(orEmptyArray(formats)));
+    }
+
+    private Response handleGetSelectedTracks() throws JSONException {
+        JSONObject tracks = RemoteApiBridge.getSelectedTracks();
+        if (tracks == null) {
+            tracks = new JSONObject();
+        }
+        return corsResponse(jsonResponse(tracks));
+    }
+
+    private Response handleSetFormat(IHTTPSession session, FormatSetter setter) throws JSONException, IOException {
+        JSONObject reqBody = parseBody(session);
+        String formatId = reqBody.getString("format_id");
+        setter.set(formatId);
+        return okResponse();
+    }
+
+    private Response handleContentOpen(IHTTPSession session) throws JSONException, IOException {
+        JSONObject reqBody = parseBody(session);
+
+        String url = reqBody.optString("url", null);
+        String videoId = reqBody.optString("video_id", null);
+        Long positionMs = reqBody.has("position_ms") ? reqBody.getLong("position_ms") : null;
+        String playlistId = reqBody.optString("playlist_id", null);
+        Integer playlistIndex = reqBody.has("playlist_index") ? reqBody.getInt("playlist_index") : null;
+
+        RemoteApiBridge.openVideo(url, videoId, positionMs, playlistId, playlistIndex);
+
+        return okResponse();
+    }
+
+    private Response handleGetSuggestions() throws JSONException {
+        return corsResponse(jsonResponse(orEmptyArray(RemoteApiBridge.getSuggestions())));
+    }
+
+    private Response handleGetRecommended() throws JSONException {
+        // Blocking network fetch (cached in the bridge) — NanoHTTPD worker thread, so OK.
+        return corsResponse(jsonResponse(orEmptyArray(RemoteApiBridge.getRecommended())));
+    }
+
+    private Response handlePlaySuggestion(String indexStr) throws JSONException {
+        int index;
+        try {
+            index = Integer.parseInt(indexStr);
+        } catch (NumberFormatException e) {
+            // Not a number — treat it as a video ID (exactly 11 chars, e.g. dQw4w9WgXcQ).
+            // ID-based play is preferred: indexes go stale when the list refreshes.
+            if (indexStr.matches("[A-Za-z0-9_-]{11}")) {
+                RemoteApiBridge.playSuggestionById(indexStr);
+                return okResponse();
+            }
+            return errorResponse(Response.Status.BAD_REQUEST, 400, "Invalid suggestion index");
+        }
+
+        RemoteApiBridge.playSuggestion(index);
+        return okResponse();
+    }
+
+    private Response handleSearchResults(IHTTPSession session) throws JSONException {
+        String query = session.getParms().get("query");
+        if (query == null || query.isEmpty()) {
+            return errorResponse(Response.Status.BAD_REQUEST, 400, "Missing query parameter");
+        }
+
+        int limit = 20;
+        String limitStr = session.getParms().get("limit");
+        if (limitStr != null && !limitStr.isEmpty()) {
+            try {
+                limit = Integer.parseInt(limitStr);
+            } catch (NumberFormatException e) {
+                return errorResponse(Response.Status.BAD_REQUEST, 400, "Invalid limit parameter");
+            }
+        }
+        limit = Math.max(1, Math.min(limit, 50));
+
+        // Blocking network fetch — NanoHTTPD worker thread, so OK.
+        return corsResponse(jsonResponse(orEmptyArray(RemoteApiBridge.searchResults(query, limit))));
+    }
+
+    private Response handleGetQueue() throws JSONException {
+        return corsResponse(jsonResponse(RemoteApiBridge.getQueue()));
+    }
+
+    private Response handleMoveQueueItem(IHTTPSession session) throws JSONException, IOException {
+        JSONObject reqBody = parseBody(session);
+        if (!reqBody.has("from") || !reqBody.has("to")) {
+            return errorResponse(Response.Status.BAD_REQUEST, 400, "Missing from/to");
+        }
+        int from = reqBody.getInt("from");
+        int to = reqBody.getInt("to");
+
+        // Reject out-of-range indices up front: Playlist.move() would otherwise throw.
+        int size = RemoteApiBridge.getQueue().length();
+        if (from < 0 || from >= size || to < 0 || to >= size) {
+            return errorResponse(Response.Status.BAD_REQUEST, 400, "Queue index out of range");
+        }
+
+        RemoteApiBridge.moveQueueItem(from, to);
+        return okResponse();
+    }
+
+    private Response handleQueuePlaylist(IHTTPSession session) throws JSONException, IOException {
+        JSONObject reqBody = parseBody(session);
+
+        String playlistId = reqBody.optString("playlist_id", null);
+        if (playlistId == null || playlistId.isEmpty()) {
+            String playlistUrl = reqBody.optString("playlist_url", null);
+            playlistId = RemoteApiBridge.extractPlaylistIdFromUrl(playlistUrl);
+        }
+        if (playlistId == null || playlistId.isEmpty()) {
+            return errorResponse(Response.Status.BAD_REQUEST, 400, "Missing playlist_id or playlist_url");
+        }
+        boolean shuffle = reqBody.optBoolean("shuffle", false);
+
+        // Blocking playlist fetch happens on this NanoHTTPD worker thread, then the
+        // queue mutation is posted to the main thread — return 202 (accepted) since
+        // the bulk add completes asynchronously from the client's perspective.
+        final String resolvedPlaylistId = playlistId;
+        RemoteApiBridge.addPlaylistToQueue(resolvedPlaylistId, shuffle);
+
+        JSONObject body = new JSONObject();
+        body.put("ok", true);
+        body.put("playlist_id", resolvedPlaylistId);
+        Response response = jsonResponse(body);
+        response.setStatus(Response.Status.ACCEPTED);
+        return corsResponse(response);
+    }
+
+    private Response handleDpad(IHTTPSession session) throws JSONException {
+        String key = session.getParms().get("key");
+        if (key == null || key.isEmpty()) {
+            return errorResponse(Response.Status.BAD_REQUEST, 400, "Missing key parameter");
+        }
+
+        RemoteApiBridge.dpad(key);
+        return okResponse();
+    }
+
+    // ---- Home Theater Handlers ----
+
+    private HomeTheaterController getTheater() {
+        return HomeTheaterController.instance(mContext);
+    }
+
+    private Response handleGetTheaterState() throws JSONException {
+        return corsResponse(jsonResponse(getTheater().getState()));
+    }
+
+    private Response handleGetTheaterVolume() throws JSONException {
+        JSONObject body = new JSONObject();
+        body.put("volume", getTheater().getVolume());
+        body.put("muted", getTheater().isMuted());
+        return corsResponse(jsonResponse(body));
+    }
+
+    private Response handleSetTheaterVolume(IHTTPSession session) throws JSONException, IOException {
+        JSONObject reqBody = parseBody(session);
+        int volume = reqBody.getInt("volume");
+        getTheater().setVolume(volume);
+        JSONObject body = new JSONObject();
+        body.put("ok", true);
+        body.put("volume", volume);
+        return corsResponse(jsonResponse(body));
+    }
+
+    private Response handleVoice(IHTTPSession session) throws JSONException, IOException {
+        JSONObject reqBody = parseBody(session);
+        String action = reqBody.getString("action");
+
+        RemoteApiBridge.voice(action);
+        return okResponse();
+    }
+
+    // ---- Response helpers ----
+
+    // The {"ok": true} acknowledgement shared by every fire-and-forget endpoint.
+    private Response okResponse() throws JSONException {
+        JSONObject body = new JSONObject();
+        body.put("ok", true);
+        return corsResponse(jsonResponse(body));
+    }
+
+    private static JSONArray orEmptyArray(JSONArray array) {
+        return array != null ? array : new JSONArray();
+    }
+
+    private String extractBearerToken(String authHeader) {
+        if (authHeader == null || authHeader.isEmpty()) {
+            return null;
+        }
+        if (authHeader.startsWith("Bearer ")) {
+            return authHeader.substring(7);
+        }
+        return null;
+    }
+
+    private JSONObject parseBody(IHTTPSession session) throws JSONException, IOException {
+        return new JSONObject(readBody(session));
+    }
+
+    private String readBody(IHTTPSession session) throws IOException {
+        Map<String, String> bodyMap = new HashMap<>();
+        try {
+            session.parseBody(bodyMap);
+        } catch (ResponseException e) {
+            throw new IOException("Failed to parse body", e);
+        }
+        // POST bodies arrive in "postData"; PUT bodies are written by NanoHTTPD to a
+        // temp file whose path is stored under "content". Without reading that file,
+        // every PUT (volume, speed, formats…) parses as "{}" and fails with 400.
+        String body = bodyMap.get("postData");
+        if (body == null) {
+            String tempFilePath = bodyMap.get("content");
+            if (tempFilePath != null) {
+                body = readFile(tempFilePath);
+            }
+        }
+        if (body == null || body.isEmpty()) {
+            body = "{}";
+        }
+        return body;
+    }
+
+    private static String readFile(String path) throws IOException {
+        java.io.FileInputStream in = new java.io.FileInputStream(path);
+        try {
+            java.io.ByteArrayOutputStream out = new java.io.ByteArrayOutputStream();
+            byte[] buffer = new byte[4096];
+            int read;
+            while ((read = in.read(buffer)) != -1) {
+                out.write(buffer, 0, read);
+            }
+            return out.toString("UTF-8");
+        } finally {
+            in.close();
+        }
+    }
+
+    private Response jsonResponse(JSONObject json) {
+        return newFixedLengthResponse(Response.Status.OK, "application/json", json.toString());
+    }
+
+    private Response jsonResponse(JSONArray json) {
+        return newFixedLengthResponse(Response.Status.OK, "application/json", json.toString());
+    }
+
+    private Response errorResponse(Response.Status status, int code, String message) {
+        try {
+            JSONObject error = new JSONObject();
+            error.put("code", code);
+            error.put("message", message);
+            JSONObject body = new JSONObject();
+            body.put("error", error);
+            Response response = newFixedLengthResponse(status, "application/json", body.toString());
+            return corsResponse(response);
+        } catch (JSONException e) {
+            return corsResponse(newFixedLengthResponse(status, "application/json",
+                    "{\"error\":{\"code\":" + code + ",\"message\":\"" + message + "\"}}"));
+        }
+    }
+
+    private Response corsResponse(Response response) {
+        response.addHeader("Access-Control-Allow-Origin", "*");
+        response.addHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+        response.addHeader("Access-Control-Allow-Headers", "Authorization, Content-Type");
+        return response;
+    }
+
+    // ---- Device info (cached) ----
+
+    private String resolveDeviceName() {
+        String name = Build.MODEL;
+        if (name == null || name.isEmpty()) {
+            name = "SmartTube Device";
+        }
+        return name;
+    }
+
+    private String resolveAppVersion() {
+        try {
+            return mContext.getPackageManager().getPackageInfo(mContext.getPackageName(), 0).versionName;
+        } catch (Exception e) {
+            return API_VERSION;
+        }
+    }
+
+    private String getDeviceName() {
+        return mDeviceName;
+    }
+
+    private String getDeviceId() {
+        // Stable per-install UUID generated/persisted by RemoteApiData (NOT the literal
+        // Settings.Secure.ANDROID_ID key string the old code returned by mistake).
+        return mApiData.getDeviceId();
+    }
+
+    private String getAppVersion() {
+        return mAppVersion;
+    }
+
+    @FunctionalInterface
+    private interface FloatSetter {
+        void set(float value);
+    }
+
+    @FunctionalInterface
+    private interface IntSetter {
+        void set(int value);
+    }
+
+    @FunctionalInterface
+    private interface BoolSetter {
+        void set(boolean value);
+    }
+
+    @FunctionalInterface
+    private interface FormatSetter {
+        void set(String formatId);
+    }
+
+    @FunctionalInterface
+    private interface StringSetter {
+        void set(String value);
+    }
+
+    private Response handleSetString(IHTTPSession session, String jsonKey, StringSetter setter) throws JSONException, IOException {
+        JSONObject reqBody = parseBody(session);
+        String value = reqBody.getString(jsonKey);
+        setter.set(value);
+        return okResponse();
+    }
+}
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/prefs/PlayerData.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/prefs/PlayerData.java
index b2595c400d..4ad31505ef 100644
--- a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/prefs/PlayerData.java
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/prefs/PlayerData.java
@@ -35,9 +35,10 @@ public class PlayerData extends DataChangeBase implements PlayerConstants, Profi
     public static final int OK_TOGGLE_SPEED = 3;
     public static final int AUTO_HIDE_NEVER = 0;
     public static final int SEEK_PREVIEW_NONE = 0;
-    public static final int SEEK_PREVIEW_SINGLE = 1;
-    public static final int SEEK_PREVIEW_CAROUSEL_SLOW = 2;
-    public static final int SEEK_PREVIEW_CAROUSEL_FAST = 3;
+    public static final int SEEK_PREVIEW_SINGLE = 1;
+    public static final int SEEK_PREVIEW_CAROUSEL_SLOW = 2;
+    public static final int SEEK_PREVIEW_CAROUSEL_FAST = 3;
+    private static final float DEFAULT_PLAYER_VOLUME = 0.50f;
     @SuppressLint("StaticFieldLeak")
     private static PlayerData sInstance;
     private final AppPrefs mPrefs;
@@ -824,7 +825,10 @@ private void restoreState() {
         mSeekIncrementMs = Helpers.parseInt(split, 37, 10_000);
         // old subs size px
         mSubtitleScale = Helpers.parseFloat(split, 39, 1.0f);
-        mPlayerVolume = Helpers.parseFloat(split, 40, 1.0f);
+        mPlayerVolume = Helpers.parseFloat(split, 40, DEFAULT_PLAYER_VOLUME);
+        if (Helpers.floatEquals(mPlayerVolume, 1.0f)) {
+            mPlayerVolume = DEFAULT_PLAYER_VOLUME;
+        }
         mIsTooltipsEnabled = Helpers.parseBoolean(split, 41, true);
         mSubtitlePosition = Helpers.parseFloat(split, 42, 0.1f);
         mIsNumberKeySeekEnabled = Helpers.parseBoolean(split, 43, true);
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/prefs/RemoteApiData.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/prefs/RemoteApiData.java
new file mode 100644
index 0000000000..3a9ca391b2
--- /dev/null
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/prefs/RemoteApiData.java
@@ -0,0 +1,268 @@
+package com.liskovsoft.smartyoutubetv2.common.prefs;
+
+import android.annotation.SuppressLint;
+import android.content.Context;
+
+import com.liskovsoft.sharedutils.helpers.Helpers;
+import com.liskovsoft.smartyoutubetv2.common.misc.remoteapi.RemoteApiConstants;
+import com.liskovsoft.smartyoutubetv2.common.prefs.common.DataChangeBase;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
+public class RemoteApiData extends DataChangeBase {
+    private static final String REMOTE_API_DATA = "remote_api_data";
+    private static final String DEVICE_NAME_DEFAULT = "Android TV";
+    private static final int DEFAULT_PORT = RemoteApiConstants.DEFAULT_PORT;
+    private static final String TOKEN_SEPARATOR = ";;";
+
+    @SuppressLint("StaticFieldLeak")
+    private static RemoteApiData sInstance;
+    private final Context mContext;
+    private final AppPrefs mAppPrefs;
+    private boolean mIsApiEnabled;
+    private int mPort;
+    private String mDeviceId;
+    private String mDeviceName;
+    private String mPairedTokens;
+    private String mPairingCode;
+    private long mPairingCodeExpiryMs;
+    private boolean mAllowAllConnections;
+
+    private RemoteApiData(Context context) {
+        mContext = context;
+        mAppPrefs = AppPrefs.instance(mContext);
+        restoreState();
+    }
+
+    public static RemoteApiData instance(Context context) {
+        if (sInstance == null) {
+            sInstance = new RemoteApiData(context.getApplicationContext());
+        }
+
+        return sInstance;
+    }
+
+    public void enableApi(boolean enable) {
+        mIsApiEnabled = enable;
+        persistState();
+    }
+
+    public boolean isApiEnabled() {
+        return mIsApiEnabled;
+    }
+
+    /** When true, any device on the local network may use the API without pairing. */
+    public boolean isAllowAllConnections() {
+        return mAllowAllConnections;
+    }
+
+    public void setAllowAllConnections(boolean allow) {
+        mAllowAllConnections = allow;
+        persistState();
+    }
+
+    public int getPort() {
+        return mPort;
+    }
+
+    public void setPort(int port) {
+        mPort = port;
+        persistState();
+    }
+
+    public String getDeviceId() {
+        return mDeviceId;
+    }
+
+    public String getDeviceName() {
+        return mDeviceName;
+    }
+
+    public void setDeviceName(String deviceName) {
+        mDeviceName = deviceName;
+        persistState();
+    }
+
+    public void addPairedToken(String token, String deviceName) {
+        if (token == null || token.isEmpty()) {
+            return;
+        }
+
+        long timestamp = System.currentTimeMillis();
+        String entry = token + ":" + (deviceName != null ? deviceName : "") + ":" + timestamp;
+
+        if (mPairedTokens == null || mPairedTokens.isEmpty()) {
+            mPairedTokens = entry;
+        } else {
+            mPairedTokens = mPairedTokens + TOKEN_SEPARATOR + entry;
+        }
+
+        persistState();
+    }
+
+    public void removePairedToken(String token) {
+        if (token == null || mPairedTokens == null || mPairedTokens.isEmpty()) {
+            return;
+        }
+
+        String[] entries = mPairedTokens.split(TOKEN_SEPARATOR);
+        StringBuilder sb = new StringBuilder();
+
+        for (String entry : entries) {
+            String[] parts = entry.split(":");
+            if (parts.length >= 1 && !parts[0].equals(token)) {
+                if (sb.length() > 0) {
+                    sb.append(TOKEN_SEPARATOR);
+                }
+                sb.append(entry);
+            }
+        }
+
+        mPairedTokens = sb.length() > 0 ? sb.toString() : "";
+        persistState();
+    }
+
+    public void removeAllTokens() {
+        mPairedTokens = "";
+        persistState();
+    }
+
+    public boolean isTokenValid(String token) {
+        if (token == null || mPairedTokens == null || mPairedTokens.isEmpty()) {
+            return false;
+        }
+
+        String[] entries = mPairedTokens.split(TOKEN_SEPARATOR);
+
+        for (String entry : entries) {
+            String[] parts = entry.split(":");
+            if (parts.length >= 1 && constantTimeEquals(parts[0], token)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Constant-time string comparison: avoids leaking a token/code's length or matching
+     * prefix through response timing (a brute-force aid on the LAN). Returns false for
+     * any null input.
+     */
+    private static boolean constantTimeEquals(String a, String b) {
+        if (a == null || b == null) {
+            return false;
+        }
+
+        byte[] ab = a.getBytes(java.nio.charset.StandardCharsets.UTF_8);
+        byte[] bb = b.getBytes(java.nio.charset.StandardCharsets.UTF_8);
+
+        int result = ab.length ^ bb.length;
+        for (int i = 0; i < ab.length; i++) {
+            byte other = i < bb.length ? bb[i] : 0;
+            result |= ab[i] ^ other;
+        }
+
+        return result == 0;
+    }
+
+    public List<String[]> getPairedDevices() {
+        List<String[]> result = new ArrayList<>();
+
+        if (mPairedTokens == null || mPairedTokens.isEmpty()) {
+            return result;
+        }
+
+        String[] entries = mPairedTokens.split(TOKEN_SEPARATOR);
+
+        for (String entry : entries) {
+            String[] parts = entry.split(":");
+            if (parts.length >= 3) {
+                result.add(new String[]{parts[0], parts[1], parts[2]});
+            } else if (parts.length == 2) {
+                result.add(new String[]{parts[0], parts[1], "0"});
+            } else if (parts.length == 1) {
+                result.add(new String[]{parts[0], "", "0"});
+            }
+        }
+
+        return result;
+    }
+
+    public void setPairingCode(String code, long expiryMs) {
+        mPairingCode = code;
+        mPairingCodeExpiryMs = expiryMs;
+        persistState();
+    }
+
+    public String getPairingCode() {
+        return mPairingCode;
+    }
+
+    public long getPairingCodeExpiryMs() {
+        return mPairingCodeExpiryMs;
+    }
+
+    public boolean isPairingCodeValid(String code) {
+        if (code == null || mPairingCode == null) {
+            return false;
+        }
+
+        if (System.currentTimeMillis() > mPairingCodeExpiryMs) {
+            return false;
+        }
+
+        return constantTimeEquals(mPairingCode, code);
+    }
+
+    /**
+     * Atomically validate and consume the active pairing code: returns true at most
+     * once for a given code, clearing it so a concurrent verify can't reuse it.
+     */
+    public synchronized boolean consumePairingCode(String code) {
+        if (!isPairingCodeValid(code)) {
+            return false;
+        }
+
+        mPairingCode = null;
+        mPairingCodeExpiryMs = 0;
+        persistState();
+        return true;
+    }
+
+    private void restoreState() {
+        String data = mAppPrefs.getData(REMOTE_API_DATA);
+
+        String[] split = Helpers.splitData(data);
+
+        mIsApiEnabled = Helpers.parseBoolean(split, 0, true);
+        mPort = Helpers.parseInt(split, 1, DEFAULT_PORT);
+        mDeviceId = Helpers.parseStr(split, 2);
+        mDeviceName = Helpers.parseStr(split, 3);
+        mPairedTokens = Helpers.parseStr(split, 4);
+        mPairingCode = Helpers.parseStr(split, 5);
+        mPairingCodeExpiryMs = Helpers.parseLong(split, 6, 0);
+        // Default ON: a home-LAN remote behaves like Chromecast (no pairing dance).
+        mAllowAllConnections = Helpers.parseBoolean(split, 7, true);
+
+        if (mDeviceId == null || mDeviceId.isEmpty()) {
+            mDeviceId = UUID.randomUUID().toString();
+            persistState();
+        }
+
+        if (mDeviceName == null || mDeviceName.isEmpty()) {
+            mDeviceName = DEVICE_NAME_DEFAULT;
+        }
+    }
+
+    private void persistState() {
+        mAppPrefs.setData(REMOTE_API_DATA, Helpers.mergeData(
+                mIsApiEnabled, mPort, mDeviceId, mDeviceName, mPairedTokens,
+                mPairingCode, mPairingCodeExpiryMs, mAllowAllConnections
+        ));
+
+        onDataChange();
+    }
+}
diff --git a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/utils/Utils.java b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/utils/Utils.java
index cfcadbfb5e..fa406ec8fe 100644
--- a/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/utils/Utils.java
+++ b/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/utils/Utils.java
@@ -5,7 +5,6 @@
 import android.app.ActivityManager;
 import android.app.ActivityManager.RunningServiceInfo;
 import android.app.AlarmManager;
-import android.app.Instrumentation;
 import android.app.KeyguardManager;
 import android.app.Notification;
 import android.app.NotificationChannel;
@@ -243,7 +242,8 @@ public static void updateRemoteControlService(Context context) {
             return;
         }
 
-        if (RemoteControlData.instance(context).isDeviceLinkEnabled()) {
+        if (RemoteControlData.instance(context).isDeviceLinkEnabled() ||
+            com.liskovsoft.smartyoutubetv2.common.prefs.RemoteApiData.instance(context).isApiEnabled()) {
             // Service that prevents the app from destroying
             startService(context, RemoteControlService.class);
         } else {
@@ -753,34 +753,76 @@ public static void showRepeatInfo(Context context, int modeIndex) {
     }
 
     /**
-     * NOTE: Doesn't work in Android 13<br/>
-     * java.lang.SecurityException: Injecting input events requires the caller (or the source of the instrumentation, if any) to have the INJECT_EVENTS permission.
+     * Deliver a key press into the app's own UI. A full ACTION_DOWN + ACTION_UP pair.
      */
     public static void sendKey(int key) {
-        if (VERSION.SDK_INT < 33) {
-            try {
-                Instrumentation instrumentation = new Instrumentation();
-                instrumentation.sendKeyDownUpSync(key);
-            } catch (SecurityException e) {
-                // Injecting to another application requires INJECT_EVENTS permission
-                e.printStackTrace();
-            }
-        }
+        sendKey(new KeyEvent(KeyEvent.ACTION_DOWN, key));
+        sendKey(new KeyEvent(KeyEvent.ACTION_UP, key));
     }
 
     /**
-     * NOTE: Doesn't work in Android 13<br/>
-     * java.lang.SecurityException: Injecting input events requires the caller (or the source of the instrumentation, if any) to have the INJECT_EVENTS permission.
+     * Deliver a single KeyEvent into the app's own current activity (D-pad remote API etc.).
+     * <p>NOTE: must NOT use Instrumentation.sendKeySync/sendKeyDownUpSync here — those call
+     * validateNotAppThread() which throws a RuntimeException on the main thread (where remote
+     * commands run), crashing the app, and system-wide injection requires INJECT_EVENTS anyway.
+     * <p>Dispatching to the current activity routes the key through the normal view hierarchy
+     * (so player controls, search box and dialogs that consume keys still work). But default
+     * D-pad focus navigation and item clicking are performed by ViewRootImpl, NOT by
+     * Activity.dispatchKeyEvent — and we bypass ViewRootImpl here. So when the view hierarchy
+     * does not consume the key, we replicate ViewRootImpl.performFocusNavigation() ourselves:
+     * move focus for the arrow keys and click the focused view for DPAD_CENTER/ENTER. (BACK is
+     * already handled inside Activity.dispatchKeyEvent, which is why it worked without this.)
      */
     public static void sendKey(KeyEvent keyEvent) {
-        if (VERSION.SDK_INT < 33) {
-            try {
-                Instrumentation instrumentation = new Instrumentation();
-                instrumentation.sendKeySync(keyEvent);
-            } catch (SecurityException e) {
-                // Injecting to another application requires INJECT_EVENTS permission
-                e.printStackTrace();
+        MotherActivity activity = MotherActivity.getCurrentActivity();
+        if (activity == null) {
+            return;
+        }
+        try {
+            // Let the view hierarchy (player overlay, search, dialogs) consume it first.
+            boolean handled = activity.dispatchKeyEvent(keyEvent);
+            if (handled || keyEvent.getAction() != KeyEvent.ACTION_DOWN) {
+                return;
             }
+
+            View decor = activity.getWindow().getDecorView();
+            int keyCode = keyEvent.getKeyCode();
+            int direction = focusDirectionFromKeyCode(keyCode);
+
+            if (direction != -1) {
+                View focused = decor.findFocus();
+                if (focused != null) {
+                    View next = focused.focusSearch(direction);
+                    if (next != null && next != focused) {
+                        next.requestFocus(direction);
+                    }
+                } else {
+                    decor.requestFocus(direction);
+                }
+            } else if (keyCode == KeyEvent.KEYCODE_DPAD_CENTER || keyCode == KeyEvent.KEYCODE_ENTER
+                    || keyCode == KeyEvent.KEYCODE_NUMPAD_ENTER) {
+                View focused = decor.findFocus();
+                if (focused != null) {
+                    focused.performClick();
+                }
+            }
+        } catch (Exception e) {
+            e.printStackTrace();
+        }
+    }
+
+    private static int focusDirectionFromKeyCode(int keyCode) {
+        switch (keyCode) {
+            case KeyEvent.KEYCODE_DPAD_LEFT:
+                return View.FOCUS_LEFT;
+            case KeyEvent.KEYCODE_DPAD_RIGHT:
+                return View.FOCUS_RIGHT;
+            case KeyEvent.KEYCODE_DPAD_UP:
+                return View.FOCUS_UP;
+            case KeyEvent.KEYCODE_DPAD_DOWN:
+                return View.FOCUS_DOWN;
+            default:
+                return -1;
         }
     }
 
diff --git a/common/src/main/res/values/strings.xml b/common/src/main/res/values/strings.xml
index 63f82610d3..80c847e49e 100644
--- a/common/src/main/res/values/strings.xml
+++ b/common/src/main/res/values/strings.xml
@@ -747,6 +747,22 @@
     <string name="enable_conscrypt">Enable Conscrypt</string>
     <string name="enable_conscrypt_desc">Improves HTTPS, TLS, and VPN compatibility on some devices, but may occasionally cause playback issues or slower network performance</string>
     <string name="network_settings">Network settings</string>
+    <string name="settings_remote_api">Remote API (Local Network)</string>
+    <string name="remote_api_enable">Enable Remote API</string>
+    <string name="remote_api_status">Status: %1$s on port %2$d</string>
+    <string name="remote_api_status_running">Running</string>
+    <string name="remote_api_status_stopped">Stopped</string>
+    <string name="remote_api_show_code">Show Pairing Code</string>
+    <string name="remote_api_current_code">Current code: %1$s</string>
+    <string name="remote_api_paired_devices">Paired Devices</string>
+    <string name="remote_api_no_devices">No paired devices</string>
+    <string name="remote_api_remove_all">Remove All Devices</string>
+    <string name="remote_api_port">Port</string>
+    <string name="remote_api_device_name">Device Name</string>
+    <string name="remote_api_code_expires">Code expires in %1$d seconds</string>
+    <string name="remote_api_allow_all">Allow all local connections (no pairing)</string>
+    <string name="remote_api_restart_port">Restart app to apply port changes</string>
+    <string name="remote_api_debug">Home Theater Debug</string>
     <string name="comments_disabled">Comments are disabled for this video</string>
     <plurals name="hours">
         <item quantity="one">%s hour</item>
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
new file mode 100644
index 0000000000..c339a07109
--- /dev/null
+++ b/docs/openapi.yaml
@@ -0,0 +1,1335 @@
+openapi: 3.0.3
+info:
+  title: SmartTube Remote Control API
+  description: |
+    Local HTTP + WebSocket API for remotely controlling a SmartTube instance on
+    Android TV — Chromecast-style playback control, browsing/search, queue
+    management, track/quality selection, video transforms, and TV volume/power.
+
+    The server (`RemoteApiServer`, NanoWSD) listens on **port 8497** by default and
+    also answers a UDP discovery probe on the same port.
+
+    ## Authentication
+
+    Two modes, controlled by the *"Allow all local connections (no pairing)"*
+    switch in *SmartTube → Settings → Remote API*:
+
+    - **Open mode (default):** `pairing_required: false`. Any device on the LAN may
+      call the API with **no token** (like Chromecast on a trusted home network).
+      The `Authorization` header is ignored if sent.
+    - **Paired mode:** `pairing_required: true`. Clients must pair (6-digit code via
+      `GET /api/pair` + `POST /api/pair/verify`) and send
+      `Authorization: Bearer <token>` on every request except `ping` and `pair`.
+
+    Discover the active mode from `GET /api/system/ping` → `pairing_required`.
+    The `bearerAuth` security scheme below is therefore **conditionally required**:
+    enforced only in paired mode.
+
+    ## Real-time updates (WebSocket)
+
+    OpenAPI 3.0 cannot describe WebSockets. In addition to the REST endpoints here,
+    the server exposes:
+
+        ws://<TV_IP>:8497/ws?token=<token>   (token omitted/empty in open mode)
+
+    On connect it sends a `hello` message, then streams `state_update` messages
+    (the `PlayerState` schema, wrapped as `{ "type": "state_update", "data": {...} }`)
+    at ~2 Hz. Clients may send the same actions as the REST endpoints as JSON
+    `{ "action": "...", ... }` frames. See `docs/remote-control-api.md` §4.10 for the
+    full command list.
+
+    ## Service discovery (UDP)
+
+    Broadcast `{"action":"discover"}` to `255.255.255.255:8497`; each instance
+    replies (unicast UDP) with `{ device_name, device_id, api_port, app_version, api_version }`.
+  version: "1.0.0"
+  license:
+    name: SmartTube project
+    url: https://github.com/yuliskov/SmartTube
+
+servers:
+  - url: http://{host}:{port}
+    description: SmartTube instance on the local network
+    variables:
+      host:
+        default: 192.168.1.100
+        description: TV IP address (find via UDP discovery or manual entry)
+      port:
+        default: "8497"
+        description: Remote API port
+
+security:
+  - bearerAuth: []   # Enforced only in paired mode; ignored in open mode.
+
+tags:
+  - name: System
+    description: Health, discovery, D-pad, and voice
+  - name: Pairing
+    description: 6-digit pairing flow (paired mode only)
+  - name: Player
+    description: Playback state and transport controls
+  - name: Playback Settings
+    description: Speed, volume, pitch, mute, subtitles
+  - name: Tracks
+    description: Video / audio / subtitle track selection
+  - name: Video Transform
+    description: Resize, zoom, rotation, flip
+  - name: Content
+    description: Open videos, search, suggestions, recommendations
+  - name: Queue
+    description: Playback queue management
+  - name: Home Theater
+    description: TV volume, mute, and power (via AudioManager)
+
+paths:
+  # ─────────────────────────── System ───────────────────────────
+  /api/system/ping:
+    get:
+      tags: [System]
+      summary: Health check + device info
+      description: Always reachable without auth. Use `pairing_required` to decide whether to run the pairing flow.
+      security: []
+      responses:
+        "200":
+          description: Device info
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Ping"
+
+  /api/system/dpad:
+    get:
+      tags: [System]
+      summary: Send a D-pad key
+      parameters:
+        - name: key
+          in: query
+          required: true
+          schema:
+            type: string
+            enum: [up, down, left, right, enter, back]
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /api/system/voice:
+    post:
+      tags: [System]
+      summary: Voice search control
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [action]
+              properties:
+                action:
+                  type: string
+                  enum: [start, stop]
+                  example: start
+      responses:
+        "200":
+          $ref: "#/components/responses/Ok"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  # ─────────────────────────── Pairing ──────────────────────────
+  /api/pair:
+    get:
+      tags: [Pairing]
+      summary: Get a pairing code
+      description: Returns a 6-digit code (also shown on the TV) valid for 5 minutes. Paired mode only, but works in open mode too.
+      security: []
+      responses:
+        "200":
+          description: Pairing code
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                    example: "482 917"
+                  expires_in:
+                    type: integer
+                    description: Seconds until the code expires
+                    example: 300
+
+  /api/pair/verify:
+    post:
+      tags: [Pairing]
+      summary: Verify a code and obtain a token
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [code]
+              properties:
+                code:
+                  type: string
+                  example: "482 917"
+      responses:
+        "200":
+          description: Bearer token
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  token:
+                    type: string
+                    description: 32-byte hex bearer token; persists until revoked
+                    example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
+                  device_name:
+                    type: string
+                    example: Living Room TV
+        "401":
+          description: Invalid pairing code
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+
+  # ─────────────────────────── Player state ─────────────────────
+  /api/player:
+    get:
+      tags: [Player]
+      summary: Full playback state
+      responses:
+        "200":
+          description: Current player state
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PlayerState"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  # ─────────────────────────── Transport ────────────────────────
+  /api/player/play:
+    post:
+      tags: [Player]
+      summary: Resume playback
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/pause:
+    post:
+      tags: [Player]
+      summary: Pause playback
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/toggle:
+    post:
+      tags: [Player]
+      summary: Toggle play/pause
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/seek:
+    post:
+      tags: [Player]
+      summary: Seek to an absolute position
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [position_ms]
+              properties:
+                position_ms:
+                  type: integer
+                  format: int64
+                  example: 60000
+      responses:
+        "200":
+          description: Seek accepted
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/Ok"
+                  - type: object
+                    properties:
+                      position_ms:
+                        type: integer
+                        format: int64
+                        example: 60000
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/next:
+    post:
+      tags: [Player]
+      summary: Next track
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/previous:
+    post:
+      tags: [Player]
+      summary: Previous track
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/stop:
+    post:
+      tags: [Player]
+      summary: Close the player
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/reload:
+    post:
+      tags: [Player]
+      summary: Reload the current source
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/pip:
+    get:
+      tags: [Player]
+      summary: Get Picture-in-Picture status
+      responses:
+        "200":
+          description: PIP state
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  active: { type: boolean, example: false }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    post:
+      tags: [Player]
+      summary: Toggle Picture-in-Picture (alias of /api/player/pip/toggle)
+      description: Back-compat alias for `POST /api/player/pip/toggle`.
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/pip/toggle:
+    post:
+      tags: [Player]
+      summary: Toggle Picture-in-Picture
+      description: |
+        Enters PIP when the player is in fullscreen; exits PIP (re-expands the player to
+        fullscreen) when already in PIP.
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/chapters:
+    get:
+      tags: [Player]
+      summary: Chapters of the current video
+      description: |
+        Chapters parsed from the playing video's YouTube metadata. Returns `[]` when
+        nothing is playing or the video has no chapters.
+      responses:
+        "200":
+          description: Chapter list
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/Chapter" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  # ─────────────────────── Playback settings ────────────────────
+  /api/player/speed:
+    get:
+      tags: [Playback Settings]
+      summary: Get playback speed
+      responses:
+        "200":
+          description: Current speed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  speed: { type: number, format: float, example: 1.0 }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    put:
+      tags: [Playback Settings]
+      summary: Set playback speed
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [speed]
+              properties:
+                speed: { type: number, format: float, example: 1.5 }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/volume:
+    get:
+      tags: [Playback Settings]
+      summary: Get player volume (0.0–1.0)
+      responses:
+        "200":
+          description: Current volume
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  volume: { type: number, format: float, minimum: 0, maximum: 1, example: 0.85 }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    put:
+      tags: [Playback Settings]
+      summary: Set player volume (0.0–1.0)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [volume]
+              properties:
+                volume: { type: number, format: float, minimum: 0, maximum: 1, example: 0.85 }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/pitch:
+    get:
+      tags: [Playback Settings]
+      summary: Get pitch
+      responses:
+        "200":
+          description: Current pitch
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  pitch: { type: number, format: float, example: 1.0 }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    put:
+      tags: [Playback Settings]
+      summary: Set pitch
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [pitch]
+              properties:
+                pitch: { type: number, format: float, example: 1.0 }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/mute:
+    get:
+      tags: [Playback Settings]
+      summary: Get mute state
+      responses:
+        "200":
+          description: Mute state
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  muted: { type: boolean, example: false }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/mute/toggle:
+    post:
+      tags: [Playback Settings]
+      summary: Toggle mute/unmute
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/subtitle:
+    get:
+      tags: [Playback Settings]
+      summary: Get subtitle (closed caption) on/off state
+      description: '"subtitle" and "closed captions" are the same thing here — `enabled` reflects whether captions are showing.'
+      responses:
+        "200":
+          description: Subtitle state
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  enabled: { type: boolean, example: true }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    put:
+      tags: [Playback Settings]
+      summary: Enable or disable subtitles (closed captions)
+      description: Deterministically turns captions on or off, unlike `POST /api/player/subtitle/toggle`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [enabled]
+              properties:
+                enabled: { type: boolean, example: true }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/subtitle/toggle:
+    post:
+      tags: [Playback Settings]
+      summary: Toggle subtitles (closed captions) on/off
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  # ─────────────────────────── Tracks ───────────────────────────
+  /api/player/formats/video:
+    get:
+      tags: [Tracks]
+      summary: List available video tracks
+      responses:
+        "200":
+          description: Video formats
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/VideoFormat" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    put:
+      tags: [Tracks]
+      summary: Select a video track
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [format_id]
+              properties:
+                format_id: { type: string, example: "30232" }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/formats/audio:
+    get:
+      tags: [Tracks]
+      summary: List available audio tracks
+      responses:
+        "200":
+          description: Audio formats
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/AudioFormat" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    put:
+      tags: [Tracks]
+      summary: Select an audio track
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [format_id]
+              properties:
+                format_id: { type: string, example: "251" }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/formats/subtitle:
+    get:
+      tags: [Tracks]
+      summary: List available subtitle tracks
+      responses:
+        "200":
+          description: Subtitle formats
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/SubtitleFormat" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    put:
+      tags: [Tracks]
+      summary: Select a subtitle track (null to disable)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                format_id:
+                  type: string
+                  nullable: true
+                  description: Subtitle format id, or null to turn subtitles off
+                  example: en
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/formats/selected:
+    get:
+      tags: [Tracks]
+      summary: Get the currently selected tracks
+      responses:
+        "200":
+          description: Selected tracks
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SelectedTracks"
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  # ──────────────────────── Video transform ─────────────────────
+  /api/player/video/resize:
+    get:
+      tags: [Video Transform]
+      summary: Get resize mode
+      responses:
+        "200":
+          description: Resize mode
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  resize_mode: { type: integer, enum: [0, 1, 2], example: 0 }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    put:
+      tags: [Video Transform]
+      summary: Set resize mode
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [mode]
+              properties:
+                mode:
+                  type: integer
+                  enum: [0, 1, 2]
+                  description: 0=fit, 1=fill, 2=zoom
+                  example: 0
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/video/zoom:
+    get:
+      tags: [Video Transform]
+      summary: Get zoom percent
+      responses:
+        "200":
+          description: Zoom percent
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  zoom_percents: { type: integer, example: 100 }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    put:
+      tags: [Video Transform]
+      summary: Set zoom percent
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [zoom]
+              properties:
+                zoom: { type: integer, example: 120 }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/video/rotation:
+    get:
+      tags: [Video Transform]
+      summary: Get rotation angle
+      responses:
+        "200":
+          description: Rotation angle
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  rotation_angle: { type: integer, enum: [0, 90, 180, 270], example: 0 }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    put:
+      tags: [Video Transform]
+      summary: Set rotation angle
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [angle]
+              properties:
+                angle: { type: integer, enum: [0, 90, 180, 270], example: 90 }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/video/flip:
+    get:
+      tags: [Video Transform]
+      summary: Get horizontal flip state
+      responses:
+        "200":
+          description: Flip state
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  flip_enabled: { type: boolean, example: false }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    put:
+      tags: [Video Transform]
+      summary: Set horizontal flip
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [enabled]
+              properties:
+                enabled: { type: boolean, example: true }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  # ─────────────────────────── Content ──────────────────────────
+  /api/content/open:
+    post:
+      tags: [Content]
+      summary: Open / play a video
+      description: |
+        Provide `url` or `video_id`. If `playlist_id` is omitted but the `url` carries
+        a `list=` query parameter, the playlist id is parsed from the url automatically.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OpenVideoRequest"
+            examples:
+              byUrl:
+                value: { url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }
+              byId:
+                value: { video_id: "dQw4w9WgXcQ" }
+              withPosition:
+                value: { video_id: "dQw4w9WgXcQ", position_ms: 30000 }
+              inPlaylist:
+                value: { video_id: "dQw4w9WgXcQ", playlist_id: "PLxxx", playlist_index: 5 }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/content/search:
+    post:
+      tags: [Content]
+      summary: Search YouTube and play the first result
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [query]
+              properties:
+                query: { type: string, example: never gonna give you up }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/content/search/results:
+    get:
+      tags: [Content]
+      summary: Search YouTube WITHOUT playing
+      description: |
+        Returns search results so the client can present them — unlike
+        `POST /api/content/search`, which plays the first hit. Play an item via
+        `POST /api/content/open` with its `video_id`.
+      parameters:
+        - name: query
+          in: query
+          required: true
+          schema: { type: string }
+          example: lofi hip hop
+        - name: limit
+          in: query
+          required: false
+          schema: { type: integer, minimum: 1, maximum: 50, default: 20 }
+          description: Clamped to 1–50.
+      responses:
+        "200":
+          description: Search results
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/VideoSummary" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/content/suggestions:
+    get:
+      tags: [Content]
+      summary: Related videos of the current video
+      description: The player's suggestion rows (related to what's playing), flattened.
+      responses:
+        "200":
+          description: Suggestion list
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/VideoSummary" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/content/suggestions/{idOrIndex}:
+    post:
+      tags: [Content]
+      summary: Play a suggestion by video ID or index
+      description: |
+        Prefer the **video ID** form (e.g. `/api/content/suggestions/dQw4w9WgXcQ`) — it
+        keeps playback context and is robust to the list refreshing. The bare index form
+        (e.g. `/api/content/suggestions/3`) is kept for compatibility but goes stale.
+      parameters:
+        - name: idOrIndex
+          in: path
+          required: true
+          schema: { type: string }
+          description: An 11-char video ID, or a zero-based index into the flattened suggestions list
+          examples:
+            byId: { value: dQw4w9WgXcQ }
+            byIndex: { value: "3" }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400":
+          description: Invalid suggestion index
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/content/recommended:
+    get:
+      tags: [Content]
+      summary: The user's Home recommendations
+      description: Cached ~5 minutes on the device. Play an item via `POST /api/content/open` with its `video_id`.
+      responses:
+        "200":
+          description: Recommended videos
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/VideoSummary" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  # ─────────────────────────── Queue ────────────────────────────
+  /api/player/queue:
+    get:
+      tags: [Queue]
+      summary: Get the playback queue
+      responses:
+        "200":
+          description: Queue items
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/QueueItem" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    post:
+      tags: [Queue]
+      summary: Add a video to the end of the queue
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/VideoIdRequest" }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    delete:
+      tags: [Queue]
+      summary: Remove a video from the queue
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/VideoIdRequest" }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/queue/next:
+    post:
+      tags: [Queue]
+      summary: Insert a video to play next
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/VideoIdRequest" }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/queue/clear:
+    post:
+      tags: [Queue]
+      summary: Clear the entire queue
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/queue/shuffle:
+    post:
+      tags: [Queue]
+      summary: Shuffle the queue
+      description: Shuffles the queue while keeping the currently-playing item in place.
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/queue/move:
+    post:
+      tags: [Queue]
+      summary: Move a queue item
+      description: Bounds-checked; out-of-range indexes are a no-op.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [from, to]
+              properties:
+                from: { type: integer, example: 2 }
+                to: { type: integer, example: 0 }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400":
+          description: Missing or non-integer from/to
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/player/queue/playlist:
+    post:
+      tags: [Queue]
+      summary: Bulk-add a whole YouTube playlist to the queue
+      description: |
+        Pass `playlist_id` **or** `playlist_url` (the `list=` param is parsed from the url).
+        Optional `shuffle` (default false). If nothing is playing, playback starts on the
+        first item. The playlist is paged on the device, capped at **500 items / 20
+        continuation pages**. Returns `202 Accepted`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                playlist_id:
+                  type: string
+                  example: PLxxx
+                playlist_url:
+                  type: string
+                  example: https://www.youtube.com/playlist?list=PLxxx
+                shuffle:
+                  type: boolean
+                  default: false
+            examples:
+              byId:
+                value: { playlist_id: "PLxxx", shuffle: false }
+              byUrl:
+                value: { playlist_url: "https://www.youtube.com/playlist?list=PLxxx" }
+      responses:
+        "202":
+          description: Playlist queue update scheduled
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok: { type: boolean, example: true }
+                  playlist_id: { type: string, example: PLxxx }
+        "400":
+          description: Neither playlist_id nor a resolvable playlist_url supplied
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  # ──────────────────────── Home Theater ────────────────────────
+  /api/theater:
+    get:
+      tags: [Home Theater]
+      summary: TV volume + mute + audio output
+      responses:
+        "200":
+          description: Theater state
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  volume: { type: integer, minimum: 0, maximum: 100, example: 42 }
+                  muted: { type: boolean, example: false }
+                  audio_output:
+                    type: string
+                    enum: [tv, theater]
+                    example: tv
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/theater/refresh:
+    get:
+      tags: [Home Theater]
+      summary: Force-refresh and return theater state
+      description: Re-reads volume/mute/output from the hardware and returns the same shape as `GET /api/theater`.
+      responses:
+        "200":
+          description: Theater state
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  volume: { type: integer, minimum: 0, maximum: 100, example: 42 }
+                  muted: { type: boolean, example: false }
+                  audio_output:
+                    type: string
+                    enum: [tv, theater]
+                    example: tv
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/theater/volume:
+    get:
+      tags: [Home Theater]
+      summary: Get TV volume + muted state
+      responses:
+        "200":
+          description: TV volume
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  volume: { type: integer, minimum: 0, maximum: 100, example: 42 }
+                  muted: { type: boolean, example: false }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+    put:
+      tags: [Home Theater]
+      summary: Set TV volume (0–100)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [volume]
+              properties:
+                volume: { type: integer, minimum: 0, maximum: 100, example: 50 }
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/theater/volume/up:
+    post:
+      tags: [Home Theater]
+      summary: Volume up one step
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/theater/volume/down:
+    post:
+      tags: [Home Theater]
+      summary: Volume down one step
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/theater/mute/toggle:
+    post:
+      tags: [Home Theater]
+      summary: Toggle TV mute
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  /api/theater/power/toggle:
+    post:
+      tags: [Home Theater]
+      summary: Toggle TV power
+      description: Sends `KEYCODE_POWER`.
+      responses:
+        "200": { $ref: "#/components/responses/Ok" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      description: |
+        `Authorization: Bearer <token>` from the pairing flow. Required only in
+        paired mode (`pairing_required: true`); ignored in open mode.
+
+  responses:
+    Ok:
+      description: Success
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/Ok" }
+    BadRequest:
+      description: Malformed JSON body or invalid/missing parameter
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/Error" }
+    Unauthorized:
+      description: Missing or invalid bearer token (paired mode)
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/Error" }
+    TooManyRequests:
+      description: Pairing rate limit exceeded (5 failed attempts/min per IP)
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/Error" }
+
+  schemas:
+    Ok:
+      type: object
+      properties:
+        ok: { type: boolean, example: true }
+
+    Error:
+      type: object
+      properties:
+        error:
+          type: object
+          properties:
+            code: { type: integer, example: 401 }
+            message: { type: string, example: Unauthorized }
+
+    Ping:
+      type: object
+      properties:
+        status: { type: string, example: ok }
+        device_name: { type: string, example: Living Room TV }
+        app_version: { type: string, example: "24.93" }
+        api_version: { type: string, example: "1" }
+        pairing_required:
+          type: boolean
+          description: false = open mode (no token needed); true = paired mode
+          example: false
+
+    VideoIdRequest:
+      type: object
+      required: [video_id]
+      properties:
+        video_id: { type: string, example: dQw4w9WgXcQ }
+
+    OpenVideoRequest:
+      type: object
+      properties:
+        url:
+          type: string
+          description: A YouTube watch/share URL (may include a `list=` playlist param)
+          example: https://www.youtube.com/watch?v=dQw4w9WgXcQ
+        video_id:
+          type: string
+          description: 11-char video ID (alternative to `url`)
+          example: dQw4w9WgXcQ
+        position_ms:
+          type: integer
+          format: int64
+          description: Start position in milliseconds
+          example: 30000
+        playlist_id:
+          type: string
+          example: PLxxx
+        playlist_index:
+          type: integer
+          example: 5
+
+    PlayerState:
+      type: object
+      properties:
+        state: { $ref: "#/components/schemas/PlaybackState" }
+        video: { $ref: "#/components/schemas/Video" }
+        position_ms: { type: integer, format: int64, example: 45000 }
+        duration_ms: { type: integer, format: int64, example: 212000 }
+        speed: { type: number, format: float, example: 1.0 }
+        pitch: { type: number, format: float, example: 1.0 }
+        volume: { type: number, format: float, example: 0.85 }
+        selected_tracks: { $ref: "#/components/schemas/SelectedTracks" }
+        video_transform: { $ref: "#/components/schemas/VideoTransform" }
+        suggestions_count: { type: integer, example: 12 }
+        queue_size: { type: integer, example: 5 }
+        queue_index: { type: integer, example: 0 }
+        queue_generation:
+          type: integer
+          description: Monotonic counter; increments on every queue change (add/remove/clear/shuffle/move). Compare across updates to cheaply detect queue changes.
+          example: 7
+
+    PlaybackState:
+      type: string
+      enum: [playing, paused, buffering, idle, ended]
+
+    Video:
+      type: object
+      properties:
+        video_id: { type: string, example: dQw4w9WgXcQ }
+        title: { type: string, example: Never Gonna Give You Up }
+        author: { type: string, example: Rick Astley }
+        channel_id: { type: string, example: UCuAXFkgsw1L7xaCfnd5JJOw }
+        thumbnail_url: { type: string, example: "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg" }
+        duration_ms: { type: integer, format: int64, example: 212000 }
+        is_live: { type: boolean, example: false }
+        is_shorts: { type: boolean, example: false }
+        playlist_id: { type: string, nullable: true, example: PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf }
+        playlist_index: { type: integer, nullable: true, example: 5 }
+
+    VideoSummary:
+      type: object
+      description: Compact video used in suggestions, recommendations, search results, and queue listings
+      properties:
+        video_id: { type: string, example: dQw4w9WgXcQ }
+        title: { type: string }
+        author: { type: string, nullable: true }
+        thumbnail_url: { type: string, nullable: true }
+        duration_ms: { type: integer, format: int64 }
+        is_live: { type: boolean }
+
+    Chapter:
+      type: object
+      properties:
+        title: { type: string, example: Intro }
+        start_ms: { type: integer, format: int64, example: 0 }
+        end_ms:
+          type: integer
+          format: int64
+          description: Start of the next chapter, or the video duration for the last one. Omitted if unknown.
+          example: 45000
+        thumbnail_url: { type: string, nullable: true }
+
+    QueueItem:
+      type: object
+      properties:
+        index: { type: integer, example: 0 }
+        video_id: { type: string, example: dQw4w9WgXcQ }
+        title: { type: string, example: Video 1 }
+        author: { type: string, nullable: true, example: Channel A }
+        thumbnail_url: { type: string, nullable: true }
+        duration_ms: { type: integer, format: int64 }
+        is_live: { type: boolean }
+        is_current: { type: boolean, example: true }
+
+    SelectedTracks:
+      type: object
+      properties:
+        video: { allOf: [{ $ref: "#/components/schemas/VideoFormat" }], nullable: true }
+        audio: { allOf: [{ $ref: "#/components/schemas/AudioFormat" }], nullable: true }
+        subtitle: { allOf: [{ $ref: "#/components/schemas/SubtitleFormat" }], nullable: true }
+
+    VideoTransform:
+      type: object
+      properties:
+        resize_mode: { type: integer, enum: [0, 1, 2], example: 0 }
+        zoom_percents: { type: integer, example: 100 }
+        rotation_angle: { type: integer, enum: [0, 90, 180, 270], example: 0 }
+        flip_enabled: { type: boolean, example: false }
+
+    VideoFormat:
+      type: object
+      properties:
+        format_id: { type: string, example: "30232" }
+        width: { type: integer, example: 1920 }
+        height: { type: integer, example: 1080 }
+        frame_rate: { type: number, format: float, example: 60.0 }
+        codec: { type: string, example: vp9 }
+        bitrate: { type: integer, example: 4500000 }
+        label: { type: string, example: 1080p60 VP9 }
+        is_selected: { type: boolean, example: true }
+
+    AudioFormat:
+      type: object
+      properties:
+        format_id: { type: string, example: "251" }
+        codec: { type: string, example: opus }
+        language: { type: string, nullable: true, example: en }
+        language_label: { type: string, nullable: true, example: English }
+        bitrate: { type: integer, example: 128000 }
+        is_selected: { type: boolean, example: true }
+
+    SubtitleFormat:
+      type: object
+      properties:
+        format_id: { type: string, example: en }
+        language: { type: string, example: en }
+        language_label: { type: string, example: English }
+        is_selected: { type: boolean, example: false }
diff --git a/docs/remote-control-api.md b/docs/remote-control-api.md
new file mode 100644
index 0000000000..51e14aa426
--- /dev/null
+++ b/docs/remote-control-api.md
@@ -0,0 +1,1072 @@
+# SmartTube Remote Control API — Complete Specification
+
+> **Status:** Ready for Implementation  
+> **Purpose:** Use this doc to build both the Android TV server and Chrome extension client
+
+---
+
+## Table of Contents
+
+1. [Architecture](#1-architecture)
+2. [Service Discovery (UDP Broadcast)](#2-service-discovery-udp-broadcast)
+3. [Authentication & Pairing](#3-authentication--pairing)
+4. [REST API Endpoints](#4-rest-api-endpoints)
+5. [WebSocket — Real-time Updates](#412-websocket--real-time-state-updates)
+6. [Data Models](#5-data-models)
+7. [Chrome Extension Spec](#6-chrome-extension-spec)
+8. [Android Implementation Plan](#7-android-implementation-plan)
+9. [Security](#8-security)
+
+---
+
+## 1. Architecture
+
+```
+Chrome Extension ──HTTP/UDP/WebSocket──► SmartTube Android TV
+                                           │
+                                     RemoteApiServer (NanoWSD, port 8497)
+                                           │
+                                     ├── HTTP REST (pairing, commands)
+                                     └── WebSocket (real-time state updates)
+                                           │
+                                     RemoteApiBridge (static adapter)
+                                           │
+                                     PlayerEngine (existing interface)
+                                           │
+                                     ExoPlayerController (existing impl)
+```
+
+**Key principle:** Zero new playback logic. The `RemoteApiBridge` is a thin adapter that maps HTTP requests to existing `PlayerEngine` methods. All playback, track selection, quality switching, etc. already exists in the codebase.
+
+---
+
+## 2. Service Discovery (UDP Broadcast)
+
+### How It Works
+
+When Remote API is enabled, the server listens for UDP broadcast probes on port 8497.
+
+**Discovery Request (Extension → TV, UDP broadcast):**
+```json
+{"action":"discover"}
+```
+
+**Discovery Response (TV → Extension, unicast UDP):**
+```json
+{
+  "device_name": "Living Room TV",
+  "device_id": "uuid-abc-123",
+  "api_port": 8497,
+  "app_version": "24.93",
+  "api_version": "1"
+}
+```
+
+The extension sends a broadcast to `255.255.255.255:8497` and each SmartTube instance responds with its info. If no TV is discovered, user enters IP manually.
+
+---
+
+## 3. Authentication & Pairing
+
+There are two modes, controlled by the **"Allow all local connections (no pairing)"** switch in *SmartTube → Settings → Remote API*:
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **Open** (default) | switch ON | Any device on the LAN may use the API **without pairing or a token**. Works like Chromecast on a trusted home network. |
+| **Paired** | switch OFF | Clients must pair (6-digit code) and send `Authorization: Bearer <token>` on every request. |
+
+A client discovers the current mode from `GET /api/system/ping` → `pairing_required` (`false` = open, `true` = paired). In open mode the `Authorization` header is ignored, so clients may omit it or send any placeholder; the WebSocket `?token=` may be empty.
+
+### Pairing Flow (only when `pairing_required: true`)
+
+```
+1. User enables "Remote API" in SmartTube settings and turns OFF "Allow all local connections"
+   → TV starts HTTP server on port 8497
+
+2. Client sends GET /api/pair
+   ← { "code": "482 917", "expires_in": 300 }
+   (the code is also shown on the TV via Settings → Remote API → Show pairing code)
+
+3. User enters code in the client
+
+4. Client sends POST /api/pair/verify
+   → { "code": "482 917" }
+   ← { "token": "a1b2c3d4...", "device_name": "Living Room TV" }
+
+5. Client stores the token
+
+6. All subsequent requests: Authorization: Bearer <token>
+```
+
+### Token Rules
+
+- 32-byte hex string, generated via `SecureRandom`
+- Persisted until explicitly revoked (no expiry)
+- Max 10 paired devices (oldest auto-revoked)
+- Pairing code: 6 digits, valid 5 minutes, 5 verification attempts/min per IP
+- In **open** mode tokens are not required and pairing is optional.
+
+---
+
+## 4. REST API Endpoints
+
+**Base URL:** `http://<TV_IP>:8497`  
+**Content-Type:** `application/json`  
+**Auth:** `Authorization: Bearer <token>` header on every endpoint except ping & pair — **unless the API is in open mode** (`pairing_required: false`), in which case auth is not required.
+
+### Error Response Format
+
+```json
+{ "error": { "code": 401, "message": "Unauthorized" } }
+```
+
+| HTTP Status | When |
+|-------------|------|
+| `400 Bad Request` | Malformed JSON body or invalid/missing parameter |
+| `401 Unauthorized` | Missing or invalid bearer token |
+| `404 Not Found` | Unknown endpoint |
+| `429 Too Many Requests` | Pairing rate limit exceeded (5 failed attempts/min per IP) |
+| `500 Internal Server Error` | Unexpected server-side error |
+
+### 4.1 System
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| `GET` | `/api/system/ping` | No | Health check + device info |
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "device_name": "Living Room TV",
+  "app_version": "24.93",
+  "api_version": "1",
+  "pairing_required": false
+}
+```
+
+- `pairing_required: false` → **open mode**: connect and use the API directly, no token needed.
+- `pairing_required: true` → **paired mode**: run the pairing flow (§3) and send `Authorization: Bearer <token>`.
+
+### 4.2 Pairing
+
+> Only needed when `pairing_required: true`. In open mode these endpoints still work but are optional.
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| `GET` | `/api/pair` | No | Get pairing code |
+| `POST` | `/api/pair/verify` | No | Verify code, get token |
+
+**`GET /api/pair` Response:**
+```json
+{ "code": "482 917", "expires_in": 300 }
+```
+
+**`POST /api/pair/verify` Request:**
+```json
+{ "code": "482 917" }
+```
+
+**`POST /api/pair/verify` Response:**
+```json
+{ "token": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "device_name": "Living Room TV" }
+```
+
+### 4.3 Player State
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| `GET` | `/api/player` | Yes | Full playback state |
+| `GET` | `/api/player/chapters` | Yes | Chapters of the current video (YouTube chapters, not SponsorBlock segments). Returns `[]` when nothing is playing or the video has no chapters |
+
+**`GET /api/player` response — see Section 5.1**
+
+**`GET /api/player/chapters` response:**
+
+```json
+[
+  { "title": "Intro", "start_ms": 0, "end_ms": 62000, "thumbnail_url": "https://i.ytimg.com/..." },
+  { "title": "Part 1", "start_ms": 62000, "end_ms": 184000, "thumbnail_url": "https://i.ytimg.com/..." }
+]
+```
+
+`end_ms` is derived: each chapter ends where the next begins; the last chapter ends at the video duration (omitted if the player can't report it). `thumbnail_url` is omitted when YouTube provides no chapter image.
+
+### 4.4 Transport Controls
+
+| Method | Endpoint | Auth | Body | Description |
+|--------|----------|------|------|-------------|
+| `POST` | `/api/player/play` | Yes | — | Resume |
+| `POST` | `/api/player/pause` | Yes | — | Pause |
+| `POST` | `/api/player/toggle` | Yes | — | Toggle play/pause |
+| `POST` | `/api/player/seek` | Yes | `{"position_ms":60000}` | Seek |
+| `POST` | `/api/player/next` | Yes | — | Next track |
+| `POST` | `/api/player/previous` | Yes | — | Previous track |
+| `POST` | `/api/player/stop` | Yes | — | Close player |
+| `POST` | `/api/player/reload` | Yes | — | Reload source |
+| `GET` | `/api/player/pip` | Yes | — | Get Picture-in-Picture status → `{ "active": false }` |
+| `POST` | `/api/player/pip/toggle` | Yes | — | Toggle Picture-in-Picture: enters PIP from fullscreen, exits (re-expands to fullscreen) when already in PIP |
+| `POST` | `/api/player/pip` | Yes | — | Back-compat alias of `/api/player/pip/toggle` |
+
+**Standard response:** `{ "ok": true }`  
+**Seek response:** `{ "ok": true, "position_ms": 60000 }`
+
+### 4.5 Playback Settings
+
+| Method | Endpoint | Auth | Body | Description |
+|--------|----------|------|------|-------------|
+| `GET` | `/api/player/speed` | Yes | — | Get speed |
+| `PUT` | `/api/player/speed` | Yes | `{"speed":1.5}` | Set speed |
+| `GET` | `/api/player/volume` | Yes | — | Get volume (0.0–1.0) |
+| `PUT` | `/api/player/volume` | Yes | `{"volume":0.85}` | Set volume |
+| `GET` | `/api/player/pitch` | Yes | — | Get pitch |
+| `PUT` | `/api/player/pitch` | Yes | `{"pitch":1.0}` | Set pitch |
+| `GET` | `/api/player/mute` | Yes | — | Get mute state |
+| `POST` | `/api/player/mute/toggle` | Yes | — | Toggle mute/unmute |
+| `GET` | `/api/player/subtitle` | Yes | — | Get subtitle (closed caption) state → `{ "enabled": true }` |
+| `PUT` | `/api/player/subtitle` | Yes | `{"enabled":true}` | Enable/disable subtitles (closed captions) deterministically |
+| `POST` | `/api/player/subtitle/toggle` | Yes | — | Toggle subtitles (closed captions) on/off |
+
+> **Subtitles = closed captions.** These three endpoints control the same on-screen captions; "subtitle" is just the player's term. Use `PUT` to set a known on/off state, or `POST .../toggle` to flip the current one.
+
+### 4.6 Track Selection
+
+| Method | Endpoint | Auth | Body | Description |
+|--------|----------|------|------|-------------|
+| `GET` | `/api/player/formats/video` | Yes | — | List video tracks |
+| `GET` | `/api/player/formats/audio` | Yes | — | List audio tracks |
+| `GET` | `/api/player/formats/subtitle` | Yes | — | List subtitle tracks |
+| `GET` | `/api/player/formats/selected` | Yes | — | Get selected tracks |
+| `PUT` | `/api/player/formats/video` | Yes | `{"format_id":"30232"}` | Select video |
+| `PUT` | `/api/player/formats/audio` | Yes | `{"format_id":"251"}` | Select audio |
+| `PUT` | `/api/player/formats/subtitle` | Yes | `{"format_id":"en"}` | Select subtitle (null to disable) |
+
+### 4.7 Video Manipulation
+
+| Method | Endpoint | Auth | Body | Description |
+|--------|----------|------|------|-------------|
+| `GET` | `/api/player/video/resize` | Yes | — | Get resize mode |
+| `PUT` | `/api/player/video/resize` | Yes | `{"mode":0}` | Set (0=fit, 1=fill, 2=zoom) |
+| `GET` | `/api/player/video/zoom` | Yes | — | Get zoom % |
+| `PUT` | `/api/player/video/zoom` | Yes | `{"zoom":120}` | Set zoom |
+| `GET` | `/api/player/video/rotation` | Yes | — | Get rotation |
+| `PUT` | `/api/player/video/rotation` | Yes | `{"angle":90}` | Set (0/90/180/270) |
+| `GET` | `/api/player/video/flip` | Yes | — | Get flip |
+| `PUT` | `/api/player/video/flip` | Yes | `{"enabled":true}` | Set flip |
+
+### 4.8 Content
+
+| Method | Endpoint | Auth | Body | Description |
+|--------|----------|------|------|-------------|
+| `POST` | `/api/content/open` | Yes | See below | Open video |
+| `POST` | `/api/content/search` | Yes | `{"query":"..."}` | Search YouTube and play first result |
+| `GET` | `/api/content/search/results?query=...&limit=20` | Yes | — | Search YouTube and return the result list as JSON **without** starting playback. `query` is required (`400` if missing); `limit` is optional (default `20`, capped at `50`). Items match the `/api/content/suggestions` shape. Play a result via `/api/content/open` with `video_id` |
+| `GET` | `/api/content/suggestions` | Yes | — | Related videos of the current video (player suggestions) |
+| `POST` | `/api/content/suggestions/:index` | Yes | — | Play a suggestion by index in the flattened list, or by **video ID** (e.g. `/api/content/suggestions/dQw4w9WgXcQ`) — ID is preferred since indexes go stale when the list refreshes |
+| `GET` | `/api/content/recommended` | Yes | — | The user's Home recommendations (cached ~5 min on device). Items: `video_id`, `title`, `author`, `thumbnail_url`, `duration_ms`, `is_live`. Play them via `/api/content/open` with `video_id`. |
+
+### 4.9 Queue Management
+
+| Method | Endpoint | Auth | Body | Description |
+|--------|----------|------|------|-------------|
+| `GET` | `/api/player/queue` | Yes | — | Get all videos in queue (items include `thumbnail_url`, `duration_ms`, `is_live`) |
+| `POST` | `/api/player/queue` | Yes | `{"video_id":"..."}` | Add video to end of queue |
+| `POST` | `/api/player/queue/next` | Yes | `{"video_id":"..."}` | Play video next |
+| `DELETE` | `/api/player/queue` | Yes | `{"video_id":"..."}` | Remove video from queue |
+| `POST` | `/api/player/queue/clear` | Yes | — | Clear entire queue |
+| `POST` | `/api/player/queue/shuffle` | Yes | — | Shuffle the queue (keeps the current item in place) |
+| `POST` | `/api/player/queue/move` | Yes | `{"from":2,"to":0}` | Move a queue item from one index to another (bounds-checked; out-of-range is a no-op). `400` if `from`/`to` are missing or non-integer |
+| `POST` | `/api/player/queue/playlist` | Yes | `{"playlist_id":"PLxxx","shuffle":false}` or `{"playlist_url":"https://www.youtube.com/playlist?list=PLxxx"}` | Bulk-add a whole YouTube playlist to the queue. Pass `playlist_id` **or** `playlist_url` (the `list=` param is parsed from the url). Optional `shuffle` (default `false`). If nothing is playing, playback starts on the first item. The playlist is paged on the device with caps of **500 items / 20 continuation pages**. Returns `202 Accepted`: `{ "ok": true, "playlist_id": "PLxxx" }`. `400` if neither `playlist_id` nor a resolvable `playlist_url` is supplied |
+
+**`GET /api/player/queue` Response:**
+```json
+[
+  { "index": 0, "video_id": "abc123", "title": "Video 1", "author": "Channel A", "is_current": true },
+  { "index": 1, "video_id": "def456", "title": "Video 2", "author": "Channel B", "is_current": false }
+]
+```
+
+**`POST /api/content/open` body variants:**
+```json
+{ "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }
+{ "video_id": "dQw4w9WgXcQ" }
+{ "video_id": "dQw4w9WgXcQ", "position_ms": 30000 }
+{ "video_id": "dQw4w9WgXcQ", "playlist_id": "PLxxx", "playlist_index": 5 }
+```
+
+If `playlist_id` is omitted but the `url` carries a `list=` query parameter (e.g. `https://www.youtube.com/watch?v=dQw4w9WgXcQ&list=PLxxx`), the playlist id is parsed from the url and applied automatically.
+
+**`GET /api/content/search/results?query=lofi+hip+hop&limit=2` Response:**
+```json
+[
+  {
+    "video_id": "jfKfPfyJRdk",
+    "title": "lofi hip hop radio - beats to relax/study to",
+    "author": "Lofi Girl",
+    "thumbnail_url": "https://i.ytimg.com/vi/jfKfPfyJRdk/maxresdefault.jpg",
+    "duration_ms": 0,
+    "is_live": true
+  },
+  {
+    "video_id": "abc123def45",
+    "title": "1 Hour Lofi Mix",
+    "author": "Some Channel",
+    "thumbnail_url": "https://i.ytimg.com/vi/abc123def45/maxresdefault.jpg",
+    "duration_ms": 3600000,
+    "is_live": false
+  }
+]
+```
+
+### 4.10 Home Theater Control
+
+Control the TV's volume, mute, and power. HDMI CEC features (output switching, subwoofer/rear levels, sound mode, immersive AE) should be implemented by the Chrome extension or an ADB bridge — see [ADB Commands for CEC](#adb-commands-for-cec-operations).
+
+| Method | Endpoint | Auth | Body | Description |
+|--------|----------|------|------|-------------|
+| `GET` | `/api/theater` | Yes | — | Volume + mute + audio output |
+| `GET` | `/api/theater/volume` | Yes | — | Get TV volume + muted state |
+| `PUT` | `/api/theater/volume` | Yes | `{"volume":50}` | Set TV volume (0–100) |
+| `POST` | `/api/theater/volume/up` | Yes | — | Volume up one step |
+| `POST` | `/api/theater/volume/down` | Yes | — | Volume down one step |
+| `POST` | `/api/theater/mute/toggle` | Yes | — | Toggle TV mute |
+| `POST` | `/api/theater/power/toggle` | Yes | — | Toggle TV power (sends `KEYCODE_POWER`) |
+| `GET` | `/api/theater/refresh` | Yes | — | Force-refresh from hardware; returns the same shape as `GET /api/theater` |
+
+**`GET /api/theater` Response:**
+```json
+{
+  "volume": 42,
+  "muted": false,
+  "audio_output": "tv"
+}
+```
+
+**`GET /api/theater/volume` Response:**
+```json
+{ "volume": 42, "muted": false }
+```
+
+#### Why HDMI CEC Needs an ADB Bridge
+
+`android.hardware.hdmi.HdmiControlManager` is a `@SystemApi` — it requires the `android.permission.MODIFY_TV_USER_SELECTION` signature-level permission, which is only granted to system apps. User-installed apps cannot access it.
+
+Similarly, the `cmd hdmi_control` shell commands require shell UID, which `Runtime.exec()` from an app does not have.
+
+**Volume and mute** use `AudioManager` — these work from any app.
+
+**CEC vendor commands** (output switching, subwoofer/rear levels, sound mode, immersive AE) must be run by an external tool that has shell access. An ADB-based bridge, a companion app installed as a system app, or a Shizuku service can execute these.
+
+#### ADB Commands for CEC Operations (for Chrome Extension / ADB Bridge)
+
+The SmartTube app cannot run these commands directly — `cmd hdmi_control` requires shell UID and `HdmiControlManager` is a `@SystemApi` unavailable to user-installed apps.
+
+The Chrome extension or an ADB bridge running on the user's machine should implement these features by executing the commands below via ADB.
+
+An extension or bridge tool running ADB commands on the user's machine can implement the full theater control. These are the exact commands:
+
+**Switch to home theater speakers:**
+```bash
+adb shell cmd hdmi_control setsystemaudiomode on
+adb shell cmd hdmi_control setarc on
+adb shell cmd hdmi_control cec_setting set volume_control_enabled 1
+```
+
+**Switch to TV speakers:**
+```bash
+adb shell cmd hdmi_control setsystemaudiomode off
+adb shell cmd hdmi_control setarc off
+```
+
+**Set subwoofer level (0–12):**
+```bash
+adb shell cmd hdmi_control vendorcommand \
+  --device_type 0 --destination 5 \
+  --args "F2:44:00:FF:06:FF:FF" --id true
+```
+Replace `06` with hex level (e.g., `08` for level 8, `00` for off).
+
+**Set rear speaker level (0–12):**
+```bash
+adb shell cmd hdmi_control vendorcommand \
+  --device_type 0 --destination 5 \
+  --args "F2:44:00:FF:FF:FF:FF:06" --id true
+```
+Replace `06` with hex level.
+
+**Set immersive audio enhancement:**
+```bash
+# Enable
+adb shell cmd hdmi_control vendorcommand \
+  --device_type 0 --destination 5 \
+  --args "F2:44:00:FF:FF:FF:01" --id true
+
+# Disable
+adb shell cmd hdmi_control vendorcommand \
+  --device_type 0 --destination 5 \
+  --args "F2:44:00:FF:FF:FF:00" --id true
+```
+
+**Set sound mode:**
+```bash
+# Auto
+adb shell cmd hdmi_control vendorcommand \
+  --device_type 0 --destination 5 \
+  --args "F2:0D:00:55:FF:FF:FF:FF" --id true
+
+# Cinema
+adb shell cmd hdmi_control vendorcommand \
+  --device_type 0 --destination 5 \
+  --args "F2:0D:00:34:FF:FF:FF:FF" --id true
+
+# Music
+adb shell cmd hdmi_control vendorcommand \
+  --device_type 0 --destination 5 \
+  --args "F2:0D:00:06:FF:FF:FF:FF" --id true
+
+# Standard
+adb shell cmd hdmi_control vendorcommand \
+  --device_type 0 --destination 5 \
+  --args "F2:0D:00:00:FF:FF:FF:FF" --id true
+```
+
+**Read current CEC state:**
+```bash
+adb shell dumpsys hdmi_control | tail -n 260
+```
+
+**Read current theater level state:**
+```bash
+adb shell cmd hdmi_control vendorcommand \
+  --device_type 0 --destination 5 \
+  --args "F2:43:00:FF:FF:FF:FF:FF" --id true
+```
+
+#### CEC State Parsing (from dumpsys output)
+
+Parse the last 260 lines of `dumpsys hdmi_control` to extract:
+
+| Pattern | Regex | Meaning |
+|---------|-------|---------|
+| Audio output | `(?:SET SYSTEM AUDIO MODE\|SYSTEM AUDIO MODE REQUEST).*(?:5F:72:\|05:70:[0-9A-F]{2}:[0-9A-F]{2}:)(00\|01)` | `01` = theater, `00` = TV |
+| Combined levels | `F2:43:00:FF:([0-9A-F]{2}):([0-9A-F]{2}):([0-9A-F]{2}):([0-9A-F]{2})` | Subwoofer, ?, Immersive, Rear |
+| Subwoofer set | `F2:44:00:FF:([0-9A-F]{2}):FF:FF` | Subwoofer level |
+| Rear set | `F2:44:00:FF:FF:FF:FF:([0-9A-F]{2})` | Rear level |
+| Immersive AE | `F2:44:00:FF:FF:FF:(00\|01)` | Immersive state |
+| Sound mode | `F2:0[CD]:00:([0-9A-F]{2}):FF:(?:00\|FF):FF:(?:00\|FF)` | Mode byte |
+
+#### Extension Implementation Pattern
+
+The Chrome extension or an ADB bridge implements full theater control:
+
+1. **Volume/mute** — use `GET/PUT /api/theater/volume` (runs on TV via AudioManager).
+2. **CEC features** — execute ADB commands directly from the user's machine:
+   - Switch audio output, set subwoofer/rear levels, sound mode, immersive AE.
+   - Parse `dumpsys hdmi_control` for current CEC state.
+3. **Power** — use `POST /api/theater/power/toggle` or ADB `input keyevent KEYCODE_POWER`.
+
+The app stores no CEC state — the bridge reads it fresh from `dumpsys hdmi_control` each time.
+
+Recommended architecture:
+
+```
+Chrome Extension ──ADB──► cmd hdmi_control (CEC features)
+                    ──REST──► SmartTube App (volume/mute/power via AudioManager)
+```
+
+The extension connects to the same REST API for player controls and volume, and runs ADB commands for HDMI CEC features.
+
+### 4.11 System Control
+
+| Method | Endpoint | Auth | Body/Params | Description |
+|--------|----------|------|-------------|-------------|
+| `GET` | `/api/system/dpad` | Yes | `?key=up` | D-pad (up/down/left/right/enter/back) |
+| `POST` | `/api/system/voice` | Yes | `{"action":"start"}` | Voice search |
+
+### 4.12 WebSocket — Real-time State Updates
+
+**URL:** `ws://<TV_IP>:8497/ws?token=<auth_token>`
+
+In **open mode** (`pairing_required: false`) the `token` query parameter is ignored and may be omitted or empty: `ws://<TV_IP>:8497/ws`.
+
+Instead of polling `GET /api/player` every second, a client can open a WebSocket connection to receive live player state updates at ~2Hz (every 500ms).
+
+#### Connection
+
+1. Open WebSocket to `ws://<TV_IP>:8497/ws?token=<your_token>` (token required only in paired mode)
+2. On connect, server sends a `hello` message
+3. Server then streams `state_update` messages every 500ms while player is active
+4. Client can send commands over the WebSocket (no HTTP needed)
+
+#### Server → Client Messages
+
+**Hello (on connect):**
+```json
+{
+  "type": "hello",
+  "api_version": "1",
+  "device_name": "Living Room TV"
+}
+```
+
+**State Update (every 500ms):**
+```json
+{
+  "type": "state_update",
+  "data": {
+    "state": "playing",
+    "video": {
+      "video_id": "dQw4w9WgXcQ",
+      "title": "Never Gonna Give You Up",
+      "author": "Rick Astley",
+      "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
+      "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
+      "duration_ms": 212000,
+      "is_live": false,
+      "is_shorts": false,
+      "playlist_id": "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf",
+      "playlist_index": 5
+    },
+    "position_ms": 45000,
+    "duration_ms": 212000,
+    "speed": 1.0,
+    "pitch": 1.0,
+    "volume": 0.85,
+    "selected_tracks": {
+      "video": { "format_id": "30232", "width": 1920, "height": 1080, "frame_rate": 60.0, "codec": "vp9", "bitrate": 4500000 },
+      "audio": { "format_id": "251", "codec": "opus", "language": "en", "bitrate": 128000 },
+      "subtitle": null
+    },
+    "video_transform": {
+      "resize_mode": 0,
+      "zoom_percents": 100,
+      "rotation_angle": 0,
+      "flip_enabled": false
+    },
+    "suggestions_count": 12,
+    "queue_size": 5,
+    "queue_index": 0,
+    "queue_generation": 7
+  }
+}
+```
+
+#### Client → Server Commands
+
+Send JSON commands over the WebSocket:
+
+| Action | Body | Description |
+|--------|------|-------------|
+| `play` | `{"action":"play"}` | Resume |
+| `pause` | `{"action":"pause"}` | Pause |
+| `toggle` | `{"action":"toggle"}` | Toggle play/pause |
+| `seek` | `{"action":"seek","position_ms":60000}` | Seek |
+| `next` | `{"action":"next"}` | Next track |
+| `previous` | `{"action":"previous"}` | Previous track |
+| `stop` | `{"action":"stop"}` | Close player |
+| `reload` | `{"action":"reload"}` | Reload source |
+| `set_speed` | `{"action":"set_speed","speed":1.5}` | Set speed |
+| `set_volume` | `{"action":"set_volume","volume":0.85}` | Set volume |
+| `set_video_format` | `{"action":"set_video_format","format_id":"30232"}` | Switch video track |
+| `set_audio_format` | `{"action":"set_audio_format","format_id":"251"}` | Switch audio track |
+| `set_subtitle_format` | `{"action":"set_subtitle_format","format_id":"en"}` | Switch subtitle (null to disable) |
+| `toggle_subtitles` | `{"action":"toggle_subtitles"}` | Toggle subtitles on/off |
+| `toggle_mute` | `{"action":"toggle_mute"}` | Toggle mute/unmute |
+| `search` | `{"action":"search","query":"never gonna give you up"}` | Search and play first result |
+| `add_to_queue` | `{"action":"add_to_queue","video_id":"dQw4w9WgXcQ"}` | Add video to queue |
+| `play_next` | `{"action":"play_next","video_id":"dQw4w9WgXcQ"}` | Play video next |
+| `remove_from_queue` | `{"action":"remove_from_queue","video_id":"dQw4w9WgXcQ"}` | Remove video from queue |
+| `clear_queue` | `{"action":"clear_queue"}` | Clear entire queue |
+| `shuffle_queue` | `{"action":"shuffle_queue"}` | Shuffle the queue (keeps current item) |
+| `move_queue_item` | `{"action":"move_queue_item","from":2,"to":0}` | Move a queue item (bounds-checked; ignored if `from`/`to` missing) |
+| `queue_playlist` | `{"action":"queue_playlist","playlist_id":"PLxxx","shuffle":false}` | Bulk-add a playlist to the queue. Accepts `playlist_id` or `playlist_url`, optional `shuffle`. Caps at 500 items / 20 pages; starts playback if idle |
+| `toggle_pip` | `{"action":"toggle_pip"}` | Toggle Picture-in-Picture (enters from fullscreen, exits when already in PIP) |
+| `get_queue` | `{"action":"get_queue"}` | Request queue list |
+| `theater_power_toggle` | `{"action":"theater_power_toggle"}` | Toggle TV power |
+| `theater_get_state` | `{"action":"theater_get_state"}` | Request theater state |
+| `get_state` | `{"action":"get_state"}` | Request immediate state update |
+
+#### Chrome Extension Usage
+
+```javascript
+class SmartTubeWebSocket {
+  constructor(host, port, token, onStateUpdate) {
+    this.url = `ws://${host}:${port}/ws?token=${token}`;
+    this.onStateUpdate = onStateUpdate;
+    this.ws = null;
+    this.reconnectDelay = 1000;
+  }
+
+  connect() {
+    this.ws = new WebSocket(this.url);
+    
+    this.ws.onopen = () => {
+      console.log('SmartTube WebSocket connected');
+      this.reconnectDelay = 1000;
+    };
+
+    this.ws.onmessage = (event) => {
+      const msg = JSON.parse(event.data);
+      
+      if (msg.type === 'hello') {
+        console.log(`Connected to ${msg.device_name}`);
+      } else if (msg.type === 'state_update') {
+        this.onStateUpdate(msg.data);
+      }
+    };
+
+    this.ws.onclose = () => {
+      console.log('WebSocket closed, reconnecting...');
+      setTimeout(() => this.connect(), this.reconnectDelay);
+      this.reconnectDelay = Math.min(this.reconnectDelay * 2, 30000);
+    };
+
+    this.ws.onerror = (err) => {
+      console.error('WebSocket error:', err);
+      this.ws.close();
+    };
+  }
+
+  send(action, params = {}) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({ action, ...params }));
+    }
+  }
+
+  play()                          { this.send('play'); }
+  pause()                         { this.send('pause'); }
+  toggle()                        { this.send('toggle'); }
+  seek(positionMs)                { this.send('seek', { position_ms: positionMs }); }
+  next()                          { this.send('next'); }
+  previous()                      { this.send('previous'); }
+  setSpeed(speed)                 { this.send('set_speed', { speed }); }
+  setVolume(volume)               { this.send('set_volume', { volume }); }
+  setVideoFormat(formatId)        { this.send('set_video_format', { format_id: formatId }); }
+  setAudioFormat(formatId)        { this.send('set_audio_format', { format_id: formatId }); }
+  setSubtitleFormat(formatId)     { this.send('set_subtitle_format', { format_id: formatId }); }
+  getState()                      { this.send('get_state'); }
+
+  disconnect() {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+}
+```
+
+#### Popup Integration Example
+
+```javascript
+// In popup.js — replace polling with WebSocket
+const ws = new SmartTubeWebSocket(host, port, token, (state) => {
+  // Update UI instantly
+  updateSeekBar(state.position_ms, state.duration_ms);
+  updatePlayPauseButton(state.state);
+  updateVolumeSlider(state.volume);
+  updateVideoTitle(state.video?.title);
+  updateThumbnail(state.video?.thumbnail_url);
+});
+
+ws.connect();
+
+// Still use REST for one-off actions like track listing
+const formats = await api.getVideoFormats();
+```
+
+#### Performance Notes
+
+- State updates are ~500 bytes each, sent at 2Hz = ~1 KB/s bandwidth
+- Server only sends updates when WebSocket clients are connected and player is active
+- No updates sent when player is idle (saves battery)
+- Auto-reconnect with exponential backoff (1s → 30s max)
+- WebSocket auth uses the same bearer token from pairing
+- Multiple clients can connect simultaneously
+
+## 5. Data Models
+
+### 5.1 Full Player State (`GET /api/player`)
+
+```json
+{
+  "state": "playing",
+  "video": {
+    "video_id": "dQw4w9WgXcQ",
+    "title": "Never Gonna Give You Up",
+    "author": "Rick Astley",
+    "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
+    "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
+    "duration_ms": 212000,
+    "is_live": false,
+    "is_shorts": false,
+    "playlist_id": "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf",
+    "playlist_index": 5
+  },
+  "position_ms": 45000,
+  "duration_ms": 212000,
+  "speed": 1.0,
+  "pitch": 1.0,
+  "volume": 0.85,
+  "selected_tracks": {
+    "video": { "format_id": "30232", "width": 1920, "height": 1080, "frame_rate": 60.0, "codec": "vp9", "bitrate": 4500000 },
+    "audio": { "format_id": "251", "codec": "opus", "language": "en", "bitrate": 128000 },
+    "subtitle": null
+  },
+  "video_transform": {
+    "resize_mode": 0,
+    "zoom_percents": 100,
+    "rotation_angle": 0,
+    "flip_enabled": false
+  },
+  "suggestions_count": 12,
+  "queue_size": 5,
+  "queue_index": 0,
+  "queue_generation": 7
+}
+```
+
+`queue_generation` is a monotonic counter that increments on every queue change (add/remove/clear/shuffle/move). Clients can compare it across state updates to cheaply detect whether the queue changed without re-fetching `GET /api/player/queue`.
+
+### 5.2 Video Format
+
+```json
+{
+  "format_id": "30232",
+  "width": 1920,
+  "height": 1080,
+  "frame_rate": 60.0,
+  "codec": "vp9",
+  "bitrate": 4500000,
+  "label": "1080p60 VP9",
+  "is_selected": true
+}
+```
+
+### 5.3 Audio Format
+
+```json
+{
+  "format_id": "251",
+  "codec": "opus",
+  "language": "en",
+  "language_label": "English",
+  "bitrate": 128000,
+  "is_selected": true
+}
+```
+
+### 5.4 Subtitle Format
+
+```json
+{
+  "format_id": "en",
+  "language": "en",
+  "language_label": "English",
+  "is_selected": false
+}
+```
+
+### 5.5 State Values
+
+| Value | Meaning |
+|-------|---------|
+| `"playing"` | Actually playing video |
+| `"paused"` | Playback paused |
+| `"buffering"` | Loading/buffering |
+| `"idle"` | No video loaded |
+| `"ended"` | Video finished |
+
+---
+
+## 6. Chrome Extension Spec
+
+### 6.1 Manifest V3
+
+```json
+{
+  "manifest_version": 3,
+  "name": "SmartTube Remote",
+  "version": "1.0.0",
+  "permissions": ["storage"],
+  "host_permissions": ["http://*:*/*"],
+  "action": { "default_popup": "popup.html", "default_icon": { "16": "icons/icon16.png", "48": "icons/icon48.png", "128": "icons/icon128.png" },
+  "background": { "service_worker": "background.js" },
+  "options_page": "options.html"
+}
+```
+
+### 6.2 File Structure
+
+```
+chrome-extension/
+├── manifest.json
+├── popup.html            # Main remote UI
+├── popup.css             # Dark theme styles
+├── popup.js              # Popup logic (fetch, polling)
+├── background.js         # Service worker (badge, background polling)
+├── options.html          # Settings: manage TVs
+├── options.js
+├── options.css
+├── lib/
+│   ├── api.js            # REST API client class
+│   ├── websocket.js      # WebSocket client for real-time updates
+│   ├── discovery.js      # UDP broadcast discovery
+│   └── storage.js        # chrome.storage wrapper
+└── icons/
+    ├── icon16.png
+    ├── icon48.png
+    └── icon128.png
+```
+
+### 6.3 `lib/api.js` — API Client
+
+```javascript
+class SmartTubeAPI {
+  constructor(baseUrl, token) {
+    this.baseUrl = baseUrl;
+    this.token = token;
+  }
+
+  async request(method, path, body = null) {
+    const opts = {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.token}`
+      }
+    };
+    if (body) opts.body = JSON.stringify(body);
+    const res = await fetch(`${this.baseUrl}${path}`, opts);
+    return res.json();
+  }
+
+  // Player
+  getPlayer()                     { return this.request('GET', '/api/player'); }
+  play()                          { return this.request('POST', '/api/player/play'); }
+  pause()                         { return this.request('POST', '/api/player/pause'); }
+  toggle()                        { return this.request('POST', '/api/player/toggle'); }
+  seek(positionMs)                { return this.request('POST', '/api/player/seek', { position_ms: positionMs }); }
+  next()                          { return this.request('POST', '/api/player/next'); }
+  previous()                      { return this.request('POST', '/api/player/previous'); }
+  stop()                          { return this.request('POST', '/api/player/stop'); }
+  reload()                        { return this.request('POST', '/api/player/reload'); }
+
+  // Speed/Volume
+  getSpeed()                      { return this.request('GET', '/api/player/speed'); }
+  setSpeed(speed)                 { return this.request('PUT', '/api/player/speed', { speed }); }
+  getVolume()                     { return this.request('GET', '/api/player/volume'); }
+  setVolume(volume)               { return this.request('PUT', '/api/player/volume', { volume }); }
+
+  // Tracks
+  getVideoFormats()               { return this.request('GET', '/api/player/formats/video'); }
+  getAudioFormats()               { return this.request('GET', '/api/player/formats/audio'); }
+  getSubtitleFormats()            { return this.request('GET', '/api/player/formats/subtitle'); }
+  getSelectedTracks()             { return this.request('GET', '/api/player/formats/selected'); }
+  setVideoFormat(formatId)        { return this.request('PUT', '/api/player/formats/video', { format_id: formatId }); }
+  setAudioFormat(formatId)        { return this.request('PUT', '/api/player/formats/audio', { format_id: formatId }); }
+  setSubtitleFormat(formatId)     { return this.request('PUT', '/api/player/formats/subtitle', { format_id: formatId }); }
+
+  // Content
+  openVideo(urlOrId, extra = {})  { return this.request('POST', '/api/content/open', { ...extra, ...(urlOrId.includes('/') ? { url: urlOrId } : { video_id: urlOrId }) }); }
+  getSuggestions()                { return this.request('GET', '/api/content/suggestions'); }
+  playSuggestion(index)           { return this.request('POST', `/api/content/suggestions/${index}`); }
+
+  // System
+  dpad(key)                       { return this.request('GET', `/api/system/dpad?key=${key}`); }
+  voice(action)                   { return this.request('POST', '/api/system/voice', { action }); }
+
+  // Pairing (static)
+  static async pair(host, port, code) {
+    const res = await fetch(`http://${host}:${port}/api/pair/verify`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ code })
+    });
+    return res.json();
+  }
+
+  static async getCode(host, port) {
+    const res = await fetch(`http://${host}:${port}/api/pair`);
+    return res.json();
+  }
+}
+```
+
+### 6.4 `lib/discovery.js` — UDP Broadcast Discovery
+
+```javascript
+async function discoverTVs(timeoutMs = 2000) {
+  // Chrome extensions can't do raw UDP, so we use a fallback:
+  // 1. Try known IPs from storage
+  // 2. Try common gateway IPs
+  // 3. Fall back to manual entry
+  // 
+  // For full UDP discovery, a native messaging host is needed.
+  // For MVP, use manual IP entry or stored IPs.
+
+  const stored = await chrome.storage.local.get('known_tvs');
+  return stored.known_tvs || [];
+}
+
+async function pingTV(host, port) {
+  try {
+    const res = await fetch(`http://${host}:${port}/api/system/ping`, { signal: AbortSignal.timeout(2000) });
+    return res.ok ? await res.json() : null;
+  } catch { return null; }
+}
+```
+
+### 6.5 UI Screens
+
+**Popup (when playing):**
+- Video thumbnail (from `video.thumbnail_url`)
+- Title + seek bar (draggable, seek on mouseup)
+- Transport: prev, rewind 10s, play/pause, forward 10s, next
+- Volume slider
+- Speed [−]/[+] buttons
+- Quality button → dropdown with video formats
+- Audio button → dropdown with audio formats
+- Subs button → dropdown with subtitle formats
+- Bottom toolbar: Search, Queue, D-pad
+
+**Pairing screen:**
+- Discovered TVs list (from ping)
+- Manual IP:port input
+- 6-digit code input
+- Connect button
+
+**Badge:**
+- Green = playing, Yellow = paused, Gray = idle, None = disconnected
+
+### 6.6 Keyboard Shortcuts (popup focused)
+
+| Key | Action |
+|-----|--------|
+| Space | Toggle play/pause |
+| ← / → | Seek ±10s |
+| ↑ / ↓ | Volume ±5% |
+| f | D-pad enter (fullscreen) |
+| Escape | Back |
+
+---
+
+## 7. Android Implementation Plan
+
+### 7.1 New Files
+
+| File | Package | Purpose |
+|------|---------|---------|
+| `RemoteApiServer.java` | `common/.../misc/remoteapi/` | NanoHTTPD server + UDP discovery listener |
+| `RemoteApiBridge.java` | `common/.../misc/remoteapi/` | HTTP→PlayerEngine adapter (static singleton) |
+| `RemoteApiAuthProvider.java` | `common/.../misc/remoteapi/` | Token generation, pairing code management |
+| `RemoteApiData.java` | `common/.../prefs/` | Settings persistence |
+| `RemoteApiSettingsPresenter.java` | `common/.../app/presenters/settings/` | Settings UI |
+
+### 7.2 Files to Modify
+
+| File | Change |
+|------|--------|
+| `common/build.gradle` | Add `nanohttpd:2.3.1` dependency |
+| `common/src/main/AndroidManifest.xml` | Add `INTERNET` permission |
+| `PlaybackPresenter.java` | Register `RemoteApiBridge` in constructor |
+| `RemoteControlService.java` | Start/stop `RemoteApiServer` |
+| `AppDataSourceManager.java` | Add "Remote API" settings entry |
+| `strings.xml` | Add new string resources |
+
+### 7.3 Key Implementation Details
+
+**RemoteApiServer (extends NanoHTTPD):**
+```java
+public class RemoteApiServer extends NanoHTTPD {
+    private RemoteApiAuthProvider mAuth;
+    
+    public RemoteApiServer(int port) {
+        super(port);
+        mAuth = new RemoteApiAuthProvider();
+    }
+    
+    @Override
+    public Response serve(IHTTPSession session) {
+        // CORS headers on all responses
+        // Auth check (skip for /api/system/ping and /api/pair)
+        // Route to handler methods
+        // Return JSON responses
+    }
+}
+```
+
+**RemoteApiBridge (static singleton, accessed by server):**
+```java
+public class RemoteApiBridge {
+    private static PlaybackPresenter sPresenter;
+    
+    public static void setPresenter(PlaybackPresenter p) { sPresenter = p; }
+    
+    public static PlayerEngine getPlayer() {
+        PlaybackView view = sPresenter.getPlayer();
+        return view != null ? view.getPlayerEngine() : null;
+    }
+    
+    public static Video getVideo() { return sPresenter.getVideo(); }
+    
+    // All endpoint handlers are static methods here
+    // e.g., handlePlay(), handleSeek(), handleGetPlayer(), etc.
+}
+```
+
+**Registration in PlaybackPresenter constructor (after RemoteController):**
+```java
+mEventListeners.add(new RemoteController(context));
+mEventListeners.add(new RemoteApiBridge()); // NEW — registers itself as static singleton
+```
+
+### 7.4 Dependencies to Add
+
+```gradle
+// common/build.gradle
+dependencies {
+    implementation 'org.nanohttpd:nanohttpd:2.3.1'
+}
+```
+
+### 7.5 Manifest Changes
+
+```xml
+<!-- common/src/main/AndroidManifest.xml -->
+<uses-permission android:name="android.permission.INTERNET" />
+```
+
+---
+
+## 8. Security
+
+| Threat | Mitigation |
+|--------|-----------|
+| Unauthorized LAN access | **Open mode (default):** none — any LAN device may control the TV (like Chromecast). Turn OFF "Allow all local connections" to require **paired-mode** bearer tokens. |
+| Brute-force pairing | 5 attempts/min per IP (paired mode) |
+| Token storage | SharedPreferences (encrypted on API 23+) |
+| MITM | HTTP only (local network, no sensitive data) |
+| DoS | rate limiting on the pairing endpoint |
+
+> **Open mode** trusts the local network. Use it on a private home Wi-Fi. On shared/public networks, disable "Allow all local connections" so clients must pair.
+
+**CORS:**
+```
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
+Access-Control-Allow-Headers: Authorization, Content-Type
+```
+
+---
+
+## Appendix: Comparison with Existing Remote Control
+
+| Feature | YouTube Device Link | REST API (this) |
+|---------|-------------------|-----------------|
+| Protocol | YouTube servers | Local HTTP |
+| Client | YouTube app only | Any HTTP client |
+| Pairing | TV code in YT app | 6-digit code in extension |
+| Commands | Play, pause, seek, volume, D-pad | All + quality, speed, zoom, search, subtitles |
+| State | Position, duration | Full: tracks, transforms, queue, metadata |
+| Latency | ~200ms (cloud) | <1ms (LAN) |
+| Internet | Required | Not required |
diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties
index 6dde6db2ae..4f67636829 100644
--- a/gradle/wrapper/gradle-wrapper.properties
+++ b/gradle/wrapper/gradle-wrapper.properties
@@ -1,6 +1,6 @@
-#Thu Jan 10 09:45:36 PST 2019
+#Thu Jun 11 16:35:34 IST 2026
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.6.6-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-bin.zip
diff --git a/gradlew b/gradlew
old mode 100644
new mode 100755
diff --git a/smarttubetv/src/main/AndroidManifest.xml b/smarttubetv/src/main/AndroidManifest.xml
index e40af8cf77..0f3e2114c8 100644
--- a/smarttubetv/src/main/AndroidManifest.xml
+++ b/smarttubetv/src/main/AndroidManifest.xml
@@ -151,6 +151,11 @@
             android:screenOrientation="unspecified"
             android:theme="@style/App.Theme.Leanback.Preferences.Opaque"/>
 
+        <activity android:name="com.liskovsoft.smartyoutubetv2.tv.ui.debug.RemoteApiDebugActivity"
+            android:exported="true"
+            android:screenOrientation="unspecified"
+            android:theme="@style/App.Theme.Leanback.Preferences"/>
+
         <activity
             android:name="com.liskovsoft.smartyoutubetv2.tv.ui.browse.BrowseActivity"
             android:launchMode="singleInstance"
diff --git a/smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/debug/RemoteApiDebugActivity.java b/smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/debug/RemoteApiDebugActivity.java
new file mode 100644
index 0000000000..890f9b1bd7
--- /dev/null
+++ b/smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/debug/RemoteApiDebugActivity.java
@@ -0,0 +1,130 @@
+package com.liskovsoft.smartyoutubetv2.tv.ui.debug;
+
+import android.app.Activity;
+import android.os.Bundle;
+import android.os.Handler;
+import android.os.Looper;
+import android.view.Gravity;
+import android.view.View;
+import android.widget.Button;
+import android.widget.LinearLayout;
+import android.widget.ScrollView;
+import android.widget.TextView;
+
+import com.liskovsoft.smartyoutubetv2.common.misc.remoteapi.HomeTheaterController;
+
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+public class RemoteApiDebugActivity extends Activity {
+    private TextView mLogView;
+    private ScrollView mScrollView;
+    private final Handler mHandler = new Handler(Looper.getMainLooper());
+    private final ExecutorService mExecutor = Executors.newSingleThreadExecutor();
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+
+        LinearLayout root = new LinearLayout(this);
+        root.setOrientation(LinearLayout.VERTICAL);
+        root.setPadding(32, 32, 32, 32);
+        root.setBackgroundColor(0xFF1A1A2E);
+
+        TextView title = new TextView(this);
+        title.setText("Remote API Debug — Theater");
+        title.setTextSize(20);
+        title.setTextColor(0xFFFFFFFF);
+        title.setPadding(0, 0, 0, 24);
+        root.addView(title);
+
+        mScrollView = new ScrollView(this);
+        mLogView = new TextView(this);
+        mLogView.setTextSize(12);
+        mLogView.setTextColor(0xFF00FF88);
+        mLogView.setTypeface(android.graphics.Typeface.MONOSPACE);
+        mLogView.setPadding(16, 16, 16, 16);
+        mLogView.setBackgroundColor(0xFF0D1117);
+        mScrollView.addView(mLogView);
+        LinearLayout.LayoutParams scrollParams = new LinearLayout.LayoutParams(
+                LinearLayout.LayoutParams.MATCH_PARENT, 0, 1f);
+        mScrollView.setLayoutParams(scrollParams);
+        root.addView(mScrollView);
+
+        // Volume row
+        LinearLayout buttonRow = new LinearLayout(this);
+        buttonRow.setOrientation(LinearLayout.HORIZONTAL);
+        buttonRow.setGravity(Gravity.CENTER);
+        buttonRow.setPadding(0, 16, 0, 0);
+
+        addButton(buttonRow, "Get Volume", () -> {
+            HomeTheaterController theater = HomeTheaterController.instance(this);
+            log("Volume: " + theater.getVolume() + "  Muted: " + theater.isMuted());
+        });
+        addButton(buttonRow, "Vol Up", () -> HomeTheaterController.instance(this).volumeUp());
+        addButton(buttonRow, "Vol Down", () -> HomeTheaterController.instance(this).volumeDown());
+        addButton(buttonRow, "Mute", () -> HomeTheaterController.instance(this).toggleMute());
+        root.addView(buttonRow);
+
+        // State row
+        LinearLayout buttonRow2 = new LinearLayout(this);
+        buttonRow2.setOrientation(LinearLayout.HORIZONTAL);
+        buttonRow2.setGravity(Gravity.CENTER);
+        buttonRow2.setPadding(0, 8, 0, 0);
+
+        addButton(buttonRow2, "Theater State", () -> {
+            HomeTheaterController theater = HomeTheaterController.instance(this);
+            try {
+                log("State:\n" + theater.getState().toString(2) + "\nOutput: " + theater.getAudioOutput());
+            } catch (Exception e) {
+                log("Error: " + e.getMessage());
+            }
+        });
+        addButton(buttonRow2, "Power", () -> HomeTheaterController.instance(this).togglePower());
+        addButton(buttonRow2, "Clear", () -> mHandler.post(() -> mLogView.setText("")));
+        root.addView(buttonRow2);
+
+        // ADB reference row
+        LinearLayout buttonRow3 = new LinearLayout(this);
+        buttonRow3.setOrientation(LinearLayout.HORIZONTAL);
+        buttonRow3.setGravity(Gravity.CENTER);
+        buttonRow3.setPadding(0, 8, 0, 0);
+
+        addButton(buttonRow3, "Show ADB Cmds", () -> log(
+            "ADB commands (run on host machine):\n\n" +
+            "Set HT:\n  adb shell cmd hdmi_control setsystemaudiomode on\n" +
+            "  adb shell cmd hdmi_control setarc on\n\n" +
+            "Set TV:\n  adb shell cmd hdmi_control setsystemaudiomode off\n" +
+            "  adb shell cmd hdmi_control setarc off\n\n" +
+            "Subwoofer (0-12):\n  adb shell cmd hdmi_control vendorcommand --device_type 0 --destination 5 --args \"F2:44:00:FF:08:FF:FF\" --id true\n\n" +
+            "Rear (0-12):\n  adb shell cmd hdmi_control vendorcommand --device_type 0 --destination 5 --args \"F2:44:00:FF:FF:FF:FF:06\" --id true\n\n" +
+            "Immersive AE:\n  adb shell cmd hdmi_control vendorcommand --device_type 0 --destination 5 --args \"F2:44:00:FF:FF:FF:01\" --id true\n\n" +
+            "Sound mode (auto/cinema/music/standard):\n  adb shell cmd hdmi_control vendorcommand --device_type 0 --destination 5 --args \"F2:0D:00:55:FF:FF:FF:FF\" --id true\n\n" +
+            "Read state:\n  adb shell dumpsys hdmi_control | tail -n 260"
+        ));
+        root.addView(buttonRow3);
+
+        setContentView(root);
+    }
+
+    private void addButton(LinearLayout row, String label, Runnable action) {
+        Button btn = new Button(this);
+        btn.setText(label);
+        btn.setTextSize(11);
+        btn.setAllCaps(false);
+        LinearLayout.LayoutParams params = new LinearLayout.LayoutParams(
+                LinearLayout.LayoutParams.WRAP_CONTENT,
+                LinearLayout.LayoutParams.WRAP_CONTENT);
+        params.setMargins(4, 0, 4, 0);
+        btn.setLayoutParams(params);
+        btn.setOnClickListener(v -> action.run());
+        row.addView(btn);
+    }
+
+    private void log(String msg) {
+        mHandler.post(() -> {
+            mLogView.append(msg + "\n\n");
+            mScrollView.post(() -> mScrollView.fullScroll(View.FOCUS_DOWN));
+        });
+    }
+}