Skip to main content
Aceplay can register itself as the default handler for acestream:// links, allowing you to click links in your browser and have them automatically open in Aceplay.

​
How it works

When you register the protocol handler, Aceplay:
  1. Creates a desktop entry file in ~/.local/share/applications/aceplay.desktop
  2. Registers the x-scheme-handler/acestream MIME type using xdg-mime
  3. Associates acestream:// links with the Aceplay application
After registration, clicking an acestream:// link in any browser will automatically launch Aceplay and start playing the stream.

​
Installation

1

Run the install command

Use either the install or register-protocol command:
aceplay install
Or:
aceplay register-protocol
Both commands perform the same action.
2

Verify the registration

Check that the desktop file was created:
cat ~/.local/share/applications/aceplay.desktop
You should see:
[Desktop Entry]
Name=Aceplay
Exec=/path/to/aceplay play %u
Type=Application
Terminal=false
MimeType=x-scheme-handler/acestream;
Categories=Network;Video;
3

Test with a browser link

Try clicking an acestream:// link in your browser. It should:
  • Prompt you to open the link with Aceplay (first time only)
  • Automatically launch Aceplay and start playing the stream

​
Desktop entry format

The desktop entry file created by Aceplay follows the Desktop Entry Specification. Here’s what each field means:
​
Name
string
Application name displayed to the user
​
Exec
string
Command to execute when the protocol is triggered. The %u is replaced with the acestream:// URL
​
Type
string
Always Application for executable programs
​
Terminal
boolean
Whether to run in a terminal. Set to false for Aceplay
​
MimeType
string
MIME type handler. Set to x-scheme-handler/acestream for acestream:// URLs
​
Categories
string
Desktop menu categories. Aceplay appears under Network and Video

​
How browser integration works

1

User clicks acestream:// link

When you click an acestream:// link in a browser, the browser checks for registered protocol handlers.
2

Desktop environment looks up handler

The desktop environment (GNOME, KDE, etc.) queries xdg-mime for the default application for x-scheme-handler/acestream.
3

Aceplay is launched

The desktop environment executes the command from the desktop file:
/usr/bin/aceplay play acestream://94c2fd8fb9bc8f2fc71a2cbe9d4b866f227a0209
4

Stream starts playing

Aceplay processes the URL and starts playing the stream using your configured player.

​
Supported browsers

The protocol handler works with all major browsers on Linux:
  • Firefox - Prompts to choose application on first use
  • Chrome/Chromium - Prompts to allow external protocol handler
  • Brave - Same behavior as Chrome
  • Edge - Same behavior as Chrome
  • Opera - Prompts to allow external application
Some browsers may remember your choice. To change the default handler, you’ll need to update browser settings or re-register the protocol.

​
Uninstalling

To remove the protocol handler: 
# Remove the desktop file
rm ~/.local/share/applications/aceplay.desktop

# Update the MIME database
update-desktop-database ~/.local/share/applications

​
Troubleshooting

Solution:Ensure the applications directory exists and is writable:
mkdir -p ~/.local/share/applications
chmod 755 ~/.local/share/applications
Then re-run:
aceplay install
Solution:This usually means the Aceplay binary path in the desktop file is incorrect.
  1. Check the desktop file: 
    cat ~/.local/share/applications/aceplay.desktop
  2. Verify the Exec path points to a valid Aceplay binary: 
    which aceplay
  3. Re-install to update the path: 
    aceplay install

​
Environment-specific notes

​
GNOME

GNOME uses the default xdg-mime system. The protocol handler should work immediately after installation.

​
KDE Plasma

KDE may cache protocol handlers. After installation, you may need to: 
kbuildsycoca5

​
i3/Sway

Window managers without a desktop environment may require additional configuration. Ensure xdg-utils is installed and a default file manager is set.

​
Reference

  • Desktop entry specification: cmd/main.go:473-481
  • Registration function: cmd/main.go:473-508
  • xdg-mime integration: cmd/main.go:500-502

Build docs developers (and LLMs) love

Get started for freeTalk to us