Register a custom protocol handler for browser integration

Author: phw

appxmanifest.xml.in

@@ -94,6 +94,12 @@
             </uap:SupportedFileTypes>
           </uap:FileTypeAssociation>
         </uap:Extension>
+        <uap:Extension Category="windows.protocol">
+          <uap:Protocol Name="%(protocol)s">
+            <uap:Logo>Square44x44Logo.targetsize-44_altform-unplated.png</uap:Logo>
+            <uap:DisplayName>%(display-name)s</uap:DisplayName>
+          </uap:Protocol>
+        </uap:Extension>
       </Extensions>
     </Application>
   </Applications>

installer/picard-setup.nsi.in

@@ -8,6 +8,7 @@
 !define PRODUCT_DESCRIPTION "%(description)s"
 !define PRODUCT_URL "%(url)s"
 !define PRODUCT_HELP_URL "https://picard-docs.musicbrainz.org/"
+!define PRODUCT_CUSTOM_PROTOCOL "%(protocol)s"
 !define PRODUCT_UNINST_KEY "Software\Microsoft\Windows\CurrentVersion\Uninstall\${PRODUCT_NAME}"
 !define PRODUCT_UNINST_ROOT_KEY "HKLM"
 
@@ -142,6 +143,11 @@ Section "!$(SectionRequired)" required
     ; Write the installation path into the registry
     WriteRegStr HKLM "Software\${PRODUCT_PUBLISHER}\${PRODUCT_NAME}" "InstallDir" "$INSTDIR"
 
+    ; Register a custom protocol handler
+    WriteRegStr HKCR "${PRODUCT_CUSTOM_PROTOCOL}" "URL Protocol" ""
+    WriteRegStr HKCR "${PRODUCT_CUSTOM_PROTOCOL}" "DefaultIcon" "$INSTDIR\picard.exe,1"
+    WriteRegStr HKCR "${PRODUCT_CUSTOM_PROTOCOL}\shell\open" "command" "$INSTDIR\picard.exe %%1"
+
     ; Create uninstaller
     WriteUninstaller "$INSTDIR\uninst.exe"
     WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "DisplayName" "${PRODUCT_NAME}"
@@ -199,6 +205,7 @@ Section Uninstall
 
   DeleteRegKey ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}"
   DeleteRegKey HKLM "Software\${PRODUCT_PUBLISHER}\${PRODUCT_NAME}"
+  DeleteRegKey HKCR "${PRODUCT_CUSTOM_PROTOCOL}"
 
   !insertmacro INSTALLOPTIONS_READ $R0 "removeSettings.ini" "Field 1" "State"
   StrCmp $R0 "1" 0 +2

org.musicbrainz.Picard.desktop.in

@@ -1,16 +1,16 @@
 [Desktop Entry]
 Name=MusicBrainz Picard
 Comment=Tag your music with the next generation MusicBrainz tagger
-Exec=picard %F
+Exec=picard %U
 Terminal=false
 Type=Application
 StartupNotify=true
 StartupWMClass=Picard
 Icon=org.musicbrainz.Picard
 Categories=AudioVideo;Audio;AudioVideoEditing;
-MimeType=application/ogg;application/x-flac;audio/aac;audio/ac3;audio/aiff;audio/ape;audio/dsf;audio/flac;audio/midi;audio/mp4;audio/mpeg;audio/mpeg4;audio/mpg;audio/ogg;audio/vorbis;audio/x-aac;audio/x-aiff;audio/x-ape;audio/x-flac;audio/x-flac+ogg;audio/x-m4a;audio/x-midi;audio/x-mp3;audio/x-mpc;audio/x-mpeg;audio/x-ms-wma;audio/x-ms-wmv;audio/x-musepack;audio/x-oggflac;audio/x-speex;audio/x-speex+ogg;audio/x-tak;audio/x-tta;audio/x-vorbis;audio/x-vorbis+ogg;audio/x-wav;audio/x-wavpack;audio/x-wma;video/x-ms-asf;video/x-theora;video/x-wmv;
+MimeType=x-scheme-handler/org.musicbrainz.picard;application/ogg;application/x-flac;audio/aac;audio/ac3;audio/aiff;audio/ape;audio/dsf;audio/flac;audio/midi;audio/mp4;audio/mpeg;audio/mpeg4;audio/mpg;audio/ogg;audio/vorbis;audio/x-aac;audio/x-aiff;audio/x-ape;audio/x-flac;audio/x-flac+ogg;audio/x-m4a;audio/x-midi;audio/x-mp3;audio/x-mpc;audio/x-mpeg;audio/x-ms-wma;audio/x-ms-wmv;audio/x-musepack;audio/x-oggflac;audio/x-speex;audio/x-speex+ogg;audio/x-tak;audio/x-tta;audio/x-vorbis;audio/x-vorbis+ogg;audio/x-wav;audio/x-wavpack;audio/x-wma;video/x-ms-asf;video/x-theora;video/x-wmv;
 Actions=new-window;
 
 [Desktop Action new-window]
 Name=New Window
-Exec=picard --stand-alone-instance %F
+Exec=picard --stand-alone-instance %U

picard.spec

@@ -10,6 +10,7 @@ sys.path.insert(0, '.')
 from picard import (
     PICARD_APP_ID,
     PICARD_APP_NAME,
+    PICARD_CUSTOM_PROTOCOL,
     PICARD_DISPLAY_NAME,
     PICARD_ORG_NAME,
     PICARD_VERSION,
@@ -163,6 +164,9 @@ else:
                 ],
                 'CFBundleTypeRole': 'Editor',
             }],
+            'CFBundleURLTypes': [{
+                'CFBundleURLSchemes': [PICARD_CUSTOM_PROTOCOL],
+            }],
         }
 
         # Add additional supported file types by extension

picard/__init__.py

@@ -44,6 +44,8 @@
 PICARD_DESKTOP_NAME = PICARD_APP_ID + ".desktop"
 PICARD_VERSION = Version(3, 0, 0, 'dev', 5)
 
+# Custom protocol for browser integration
+PICARD_CUSTOM_PROTOCOL = 'org.musicbrainz.picard'
 
 # optional build version
 # it should be in the form '<platform>_<YYMMDDHHMMSS>'

picard/browser/browser.py

@@ -5,7 +5,7 @@
 # Copyright (C) 2006-2007, 2011 Lukáš Lalinský
 # Copyright (C) 2011-2013 Michael Wiencek
 # Copyright (C) 2012 Chad Wilson
-# Copyright (C) 2012-2013, 2018, 2021-2022, 2024 Philipp Wolfer
+# Copyright (C) 2012-2013, 2018, 2021-2022, 2024-2025 Philipp Wolfer
 # Copyright (C) 2013, 2018, 2020-2021, 2024 Laurent Monin
 # Copyright (C) 2016 Suhas
 # Copyright (C) 2016-2017 Sambhav Kothari
@@ -38,9 +38,11 @@
 )
 
 from PyQt6 import QtCore
+from PyQt6.QtGui import QDesktopServices
 
 from picard import (
     PICARD_APP_NAME,
+    PICARD_CUSTOM_PROTOCOL,
     PICARD_ORG_NAME,
     PICARD_VERSION_STR,
     log,
@@ -86,6 +88,8 @@ class BrowserIntegration(QtCore.QObject):
     def __init__(self, parent=None):
         super().__init__(parent)
         self.server = None
+        self._action_handler = RequestActionHandler()
+        QDesktopServices.setUrlHandler(PICARD_CUSTOM_PROTOCOL, self.url_handler)
 
     @property
     def host_address(self):
@@ -129,7 +133,7 @@ def start(self):
         except Exception:
             log.error("Failed starting the browser integration on %s", host_address, exc_info=True)
 
-    def stop(self):
+    def stop(self, stop_url_handler=False):
         if self.server:
             try:
                 log.info("Stopping the browser integration")
@@ -142,9 +146,24 @@ def stop(self):
         else:
             log.debug("Browser integration inactive, no need to stop")
 
+        if stop_url_handler:
+            QDesktopServices.unsetUrlHandler(PICARD_CUSTOM_PROTOCOL)
+
+    def url_handler(self, url: QtCore.QUrl):
+        """URL handler used for custom protocol handling."""
+        if url.scheme() != PICARD_CUSTOM_PROTOCOL:
+            log.error("Invalid URL scheme: %s", url.scheme())
+            return
+
+        self._action_handler.handle_get(url.toString())
+
 
 class RequestHandler(BaseHTTPRequestHandler):
 
+    def __init__(self, *args, **kwargs):
+        self._action_handler = RequestActionHandler(self._response)
+        super().__init__(*args, **kwargs)
+
     def do_OPTIONS(self):
         origin = self.headers['origin']
         if _is_valid_origin(origin):
@@ -161,7 +180,7 @@ def do_OPTIONS(self):
 
     def do_GET(self):
         try:
-            self._handle_get()
+            self._action_handler.handle_get(self.path)
         except Exception:
             log.error('Browser integration failed handling request', exc_info=True)
             self._response(500, 'Unexpected request error')
@@ -172,10 +191,32 @@ def log_error(self, format, *args):
     def log_message(self, format, *args):
         log.info(format, *args)
 
-    def _handle_get(self):
-        parsed = urlparse(self.path)
+    def _response(self, code, content='', content_type='text/plain'):
+        self.server_version = SERVER_VERSION
+        self.send_response(code)
+        self.send_header('Content-Type', content_type)
+        self.send_header('Cache-Control', 'max-age=0')
+        origin = self.headers['origin']
+        if _is_valid_origin(origin):
+            self.send_header('Access-Control-Allow-Origin', origin)
+            self.send_header('Vary', 'Origin')
+        self.end_headers()
+        self.wfile.write(content.encode())
+
+
+class RequestActionHandler:
+    """
+    Handles URL requests by executing the appropriate action based on URL path.
+    """
+    def __init__(self, response_handler=None):
+        self._response_handler = response_handler
+
+    def handle_get(self, path):
+        parsed = urlparse(path)
         args = parse_qs(parsed.query)
         action = parsed.path
+        if not action.startswith('/'):
+            action = '/' + action
 
         if action == '/':
             self._response(200, SERVER_VERSION)
@@ -188,6 +229,7 @@ def _handle_get(self):
         elif action == '/auth':
             self._auth(args)
         else:
+            log.error('Unknown browser action: %s', action)
             self._response(404, 'Unknown action.')
 
     def _load_mbid(self, type, args):
@@ -235,13 +277,8 @@ def _auth(self, args):
             self._response(400, 'Missing parameter "code".')
 
     def _response(self, code, content='', content_type='text/plain'):
-        self.server_version = SERVER_VERSION
-        self.send_response(code)
-        self.send_header('Content-Type', content_type)
-        self.send_header('Cache-Control', 'max-age=0')
-        origin = self.headers['origin']
-        if _is_valid_origin(origin):
-            self.send_header('Access-Control-Allow-Origin', origin)
-            self.send_header('Vary', 'Origin')
-        self.end_headers()
-        self.wfile.write(content.encode())
+        if not self._response_handler:
+            log.debug(f'Finished custom request with code {code}')
+            return
+
+        self._response_handler(code, content, content_type)

picard/tagger.py

@@ -69,6 +69,7 @@
 from picard import (
     PICARD_APP_ID,
     PICARD_APP_NAME,
+    PICARD_CUSTOM_PROTOCOL,
     PICARD_FANCY_VERSION_STR,
     PICARD_ORG_NAME,
     acoustid,
@@ -191,6 +192,7 @@ def __init__(self, items):
         self.files = set()
         self.mbids = set()
         self.urls = set()
+        self.custom_urls = set()
 
         for item in items:
             parsed = urlparse(item)
@@ -205,6 +207,8 @@ def __init__(self, items):
             elif parsed.scheme in {'http', 'https'}:
                 # .path returns / before actual link
                 self.urls.add(parsed.path[1:])
+            elif parsed.scheme == PICARD_CUSTOM_PROTOCOL:
+                self.custom_urls.add(item)
             elif IS_WIN and self.WINDOWS_DRIVE_TEST.match(item):
                 # Treat all single-character schemes as part of the file spec to allow
                 # specifying a drive identifier on Windows systems.
@@ -519,6 +523,10 @@ def handle_command_load(self, argstring):
             for item in parsed_items.mbids | parsed_items.urls:
                 file_lookup.mbid_lookup(item)
 
+        if parsed_items.custom_urls:
+            for item in parsed_items.custom_urls:
+                self.browser_integration.url_handler(QtCore.QUrl(item))
+
     def handle_command_lookup(self, argstring):
         if argstring:
             argstring = argstring.upper()
@@ -765,7 +773,7 @@ def exit(self):
         if self.priority_thread_pool:
             self.priority_thread_pool.waitForDone()
         if self.browser_integration:
-            self.browser_integration.stop()
+            self.browser_integration.stop(stop_url_handler=True)
         self.run_cleanup()
         QtCore.QCoreApplication.processEvents()
 
@@ -1517,7 +1525,7 @@ def process_picard_args():
 
     args.processable = []
     for path in args.FILE_OR_URL:
-        if not urlparse(path).netloc:
+        if not urlparse(path).scheme:
             try:
                 path = os.path.abspath(path)
             except FileNotFoundError:

setup.py

@@ -63,6 +63,7 @@
 from picard import (  # noqa: E402
     PICARD_APP_ID,
     PICARD_APP_NAME,
+    PICARD_CUSTOM_PROTOCOL,
     PICARD_DESKTOP_NAME,
     PICARD_DISPLAY_NAME,
     PICARD_VERSION,
@@ -167,6 +168,7 @@ def run(self):
             installer_args = {
                 'display-name': PICARD_DISPLAY_NAME,
                 'file-version': file_version_str,
+                'protocol': PICARD_CUSTOM_PROTOCOL,
             }
             if os.path.isfile('installer/picard-setup.nsi.in'):
                 generate_file('installer/picard-setup.nsi.in', 'installer/picard-setup.nsi', {**common_args, **installer_args})
@@ -190,6 +192,7 @@ def run(self):
                 'short-name': PICARD_APP_NAME,
                 'publisher': os.environ.get('PICARD_APPX_PUBLISHER', default_publisher),
                 'version': '.'.join(str(v) for v in store_version),
+                'protocol': PICARD_CUSTOM_PROTOCOL,
             })
         elif sys.platform not in {'darwin', 'haiku1', 'win32'}:
             self.run_command('build_appdata')