Concept

Summary

When the command handler script (yt-download.ps1) is installed, a new URL protocol handler, ytdl:, is added to the OS. The first time you open a URL using this protocol in your browser, your OS will notify you that there is a handler to open this URL. The job of the user script installed in your browser is to create and open the URL with parameters, which then opens the protocol handler on your OS that processes the URL and its parameters. All of this happens with a single click.

In our case, a ytdl: protocol runs a Powershell script to parse the passed URL parameters then runs the appropriate yt-dlp command to download content.

Details (for nerds)

What is a custom URL protocol in general ?

A custom URL protocol is a mechanism that allows applications to register and handle specific URL schemes on a user's device. It enables a web browser or operating system to launch a specific application when a URL with a custom scheme is accessed. For example, instead of standard protocols like http: or https:, a custom protocol might use a scheme like myapp:.

How It Works

1. Registration: An application registers a custom URL scheme (e.g., myapp:) with the operating system. This is typically done during the application's installation or setup process. The registration associates the scheme with the application, specifying how to handle URLs that use it.
2. URL Format: A custom URL follows the format scheme://[optional-data]. For example, myapp://open?file=123 could instruct the "myapp" application to open a specific file.
3. Triggering: When a user clicks a link with the custom scheme (e.g., in a browser or email), the operating system recognizes the scheme and launches the associated application, passing the URL data to it.
4. Handling: The application processes the URL, extracting parameters or instructions embedded in it to perform specific actions (e.g., opening a file, starting a call, or navigating to a specific section).

Common Examples

• mailto:: Opens the default email client (e.g., mailto:user@example.com).
• tel:: Initiates a phone call (e.g., tel:+1234567890).
• spotify:: Opens the Spotify app to play specific content (e.g., spotify:track:123).
• zoommtg:: Launches a Zoom meeting (e.g., zoommtg://zoom.us/join?confno=123).

Use Cases

• Seamless App Integration: Custom protocols allow web-to-app or app-to-app communication, enabling smooth user experiences (e.g., clicking a link to open a specific app feature).
• Automation: Developers can use custom URLs to trigger specific actions in their applications, such as pre-filling forms or navigating to specific content.
• Cross-Platform Functionality: They work across browsers, emails, or other platforms, as long as the application is installed and registered.

Implementation

To create a custom URL protocol:

1. Register the Protocol:
   • On Windows, modify the registry to associate the scheme with the application (e.g., under HKEY_CLASSES_ROOT).
   • On macOS, add the scheme to the application's Info.plist file under CFBundleURLTypes.
   • On Linux, use xdg-mime or similar tools to register the scheme.
2. Handle the URL in the Application:
   • The application must parse the incoming URL and map it to specific functionality (e.g., extracting query parameters or path segments).
3. Test Thoroughly:
   • Ensure the protocol works across different browsers and platforms, and handle cases where the application is not installed.

Security Considerations

• Malicious URLs: Custom protocols can be exploited if not validated properly, as they may allow arbitrary commands to be executed.
• User Consent: Always prompt users before performing sensitive actions triggered by a URL.
• Sanitization: Validate and sanitize URL parameters to prevent injection attacks.

Don’t use scripts that are not easy to read and understand. This repo provides a secure way to use a protocol to run yt-dlp command or to create your own protocol and application handler.

Limitations

• The application must be installed on the user's device for the protocol to work.
• Not all browsers or platforms handle custom protocols consistently.
  • Tested successfully on Firefox, Edge and Vivaldi on Windows 10. Create an issue to report a failure on another setup.
• If multiple applications register the same scheme, conflicts may arise.

In summary, custom URL protocols provide a powerful way to bridge web and native applications, enabling seamless interactions but requiring careful implementation to ensure security and compatibility.