From 9e2cab0e95c79e187ce26830bd5aa0c4763bc842 Mon Sep 17 00:00:00 2001
From: Cognis Digital <215970675+cognis-digital@users.noreply.github.com>
Date: Fri, 26 Jun 2026 05:49:37 -0400
Subject: [PATCH] Fix spurious 'MPV start timed out' on Windows (named-pipe
 readiness)

MPVProcess polled os.path.exists(ipc_socket) to detect the IPC endpoint
before returning. On Windows the endpoint is a named pipe, and
os.path.exists() is always False for \.\pipe\ paths, so the 10s poll
never detected the pipe and startup raised 'MPV start timed out' even
though MPV was running and the pipe was live.

Probe the pipe with _winapi.WaitNamedPipe on Windows (the transport layer
already uses _winapi); POSIX behavior is unchanged (still os.path.exists).
---
 python_mpv_jsonipc.py | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/python_mpv_jsonipc.py b/python_mpv_jsonipc.py
index bd35bbd..f6a6082 100644
--- a/python_mpv_jsonipc.py
+++ b/python_mpv_jsonipc.py
@@ -198,6 +198,26 @@ def run(self):
         if self.quit_callback:
             self.quit_callback()
 
+def _ipc_endpoint_ready(ipc_socket):
+    """Return True once MPV's IPC endpoint is available.
+
+    On POSIX the endpoint is a filesystem socket, so ``os.path.exists`` works. On
+    Windows it is a *named pipe*, for which ``os.path.exists`` is always False — so we
+    probe it with ``WaitNamedPipe`` instead. Using ``os.path.exists`` on Windows made
+    the startup poll never detect the pipe, raising a spurious "MPV start timed out".
+    """
+    if os.name != 'nt':
+        return os.path.exists(ipc_socket)
+    try:
+        _winapi.WaitNamedPipe(ipc_socket, 0)
+        return True
+    except FileNotFoundError:
+        return False
+    except OSError:
+        # Pipe exists but all instances are momentarily busy — it is present.
+        return True
+
+
 class MPVProcess:
     """
     Manages an MPV process, ensuring the socket or pipe is available. (Internal)
@@ -248,7 +268,7 @@ def __init__(self, ipc_socket, mpv_location=None, **kwargs):
         for _ in range(100): # Give MPV 10 seconds to start.
             time.sleep(0.1)
             self.process.poll()
-            if os.path.exists(ipc_socket):
+            if _ipc_endpoint_ready(ipc_socket):
                 ipc_exists = True
                 log.debug("Found MPV socket.")
                 break