Difference between revisions of "Mumble URL"

From Mumble Wiki
Jump to: navigation, search
m (removed documentation category)
 
(15 intermediate revisions by 6 users not shown)
Line 1: Line 1:
Mumble supports an own URL concept which enables you to join Mumble servers by a click of a link on a website, via links in your Desktop system or via the "Run" dialog of your system.  
+
Mumble supports an own URL concept which enables you to join Mumble servers by a click of a link on a website, via links in the Mumble client (eg, in [[Murmur.ini#welcometext|MOTD]]/chat messages, but only if [[Murmur.ini#allowhtml|AllowHTML]] is set to true), via links in your Desktop system or via the "Run" dialog of your system.
  
 
Mumble will also accept URLs as command line arguments:
 
Mumble will also accept URLs as command line arguments:
Line 5: Line 5:
 
Example:
 
Example:
  
  mumble.exe mumble://172.16.31.199/
+
  mumble.exe mumble://server.com/?version=1.2.0
  
== URL Handler Installation ==
+
Beginning with 1.2.4, you can grab a URL to the current server/channel by right clicking the channel and selecting "Copy URL". Note that also beginning with 1.2.4, "?version" is not required, but it's still recommended that you include it as anyone who has 1.2.3 or earlier will launch the 1.1.x compatibility client when clicking links without "?version=1.2.0".
 +
 
 +
=== General URL ===
 +
 
 +
Mumble uses normal URLs with the "mumble" scheme.
 +
 
 +
mumble://[username[:password]@]<address>[:port]/[channelpath]?version=<serverversion>[&title=<servername>][&url=<serverurl>]
 +
 
 +
'''username''' and '''password''' are optional.
  
If you have compiled Mumble from it's sources by yourself, the feature will not be available at first. You will have to register Mumble as a protocol handler for it's own URL type for your Desktop system in that case. If you installed Mumble with it's official installer, Mumble URLs should be accepeted by your Desktop system, in that case, you can ignore this section.
+
'''address''' is mandatory, and can be a IPv4 or IPv6 numerical address, or a hostname.
  
=== Gnome ===
+
'''port''' is optional, and 64738 is the default if not specified.
  
To enable Mumble URLs in the Gnome Desktop System on Linux, you have to execute the following commands:
+
'''channelpath''' is the path to the channel the client should try to move into. If the channel does not exist, the client will stay in the default channel.
  
gconftool-2 -s -t string /desktop/gnome/url-handlers/mumble/command 'mumble "%s"'
+
'''serverversion''' is the protocol version of the server. This should be ''1.1.0'' for 1.1 servers, and ''1.2.0'' for 1.2. For the time being, ''1.1.0'' will be assumed if this parameter is missing, but once the majority of users have switched to the 1.2 release, the default will be 1.2.0 to make URLs shorter.
gconftool-2 -s -t bool /desktop/gnome/url-handlers/mumble/enabled true
 
  
If the "mumble" command is not globally accessible through the PATH environment variable, you must specify it's full path instead of the last "mumble" in the first of the two commands above.
+
'''servername''' and '''serverurl''' are optional, and only used if the user drags the link and drops it in the server browser in Mumble. As this is a conventient way to add the server, we recommend they be filled out.
  
== URL Composition ==
+
Remember to encode special characters with their % equivalent. Most URL classes will do this for you.
  
 
=== Simple Server Address ===
 
=== Simple Server Address ===
Line 26: Line 33:
 
Scheme:
 
Scheme:
  
  mumble://[SERVER ADDRESS]:[PORT]/
+
  mumble://[SERVER ADDRESS]:[PORT]/?version=1.2.0
  
 
Examples:
 
Examples:
  
  mumble://server.com/
+
  mumble://server.com/?version=1.2.0
  mumble://172.16.31.199/
+
  mumble://172.16.31.199/?version=1.2.0
  mumble://server.com:23840/
+
  mumble://server.com:23840/?version=1.2.0
  mumble://172.16.31.199:2000/
+
  mumble://172.16.31.199:2000/?version=1.2.0
  
 
This method simply enables you to join a server via an URL. Mumble will ask you instantly for your username and, if needed, for your password. As you can see in the examples, you are free to specify either an IP address or a DNS Name which represents the server you want to join. If the Mumble server does not listen on the default Mumble Port (64738), you can specify a port number after a separating colon.
 
This method simply enables you to join a server via an URL. Mumble will ask you instantly for your username and, if needed, for your password. As you can see in the examples, you are free to specify either an IP address or a DNS Name which represents the server you want to join. If the Mumble server does not listen on the default Mumble Port (64738), you can specify a port number after a separating colon.
 +
 
=== Username ===
 
=== Username ===
  
 
Scheme:
 
Scheme:
  
  mumble://[USERNAME]@[SERVER ADDRESS]:[PORT]/
+
  mumble://[USERNAME]@[SERVER ADDRESS]:[PORT]/?version=1.2.0
  
 
Examples:
 
Examples:
  
  mumble://TestUser@server.com/
+
  mumble://TestUser@server.com/?version=1.2.0
  mumble://TheGimp@172.16.31.199/
+
  mumble://TheGimp@172.16.31.199/?version=1.2.0
  mumble://TestUser@server.com:23840/
+
  mumble://TestUser@server.com:23840/?version=1.2.0
  mumble://TheGimp@172.16.31.199:2000/
+
  mumble://TheGimp@172.16.31.199:2000/?version=1.2.0
  
 
This method simply enables you to join a server via an URL with an already specified username. Mumble will ask you instantly for your password, if this should be needed.
 
This method simply enables you to join a server via an URL with an already specified username. Mumble will ask you instantly for your password, if this should be needed.
Line 55: Line 63:
 
Scheme:
 
Scheme:
  
  mumble://[USERNAME]:[PASSWORD]@[SERVER ADDRESS]:[PORT]/
+
  mumble://[USERNAME]:[PASSWORD]@[SERVER ADDRESS]:[PORT]/?version=1.2.0
  
 
Examples:
 
Examples:
  
  mumble://TestUser:mypassword@server.com/
+
  mumble://TestUser:mypassword@server.com/?version=1.2.0
  mumble://TheGimp:ilovezed@172.16.31.199/
+
  mumble://TheGimp:ilovezed@172.16.31.199/?version=1.2.0
  mumble://TestUser:mypassword@server.com:23840/
+
  mumble://TestUser:mypassword@server.com:23840/?version=1.2.0
  mumble://TheGimp:ilovezed@172.16.31.199:2000/
+
  mumble://TheGimp:ilovezed@172.16.31.199:2000/?version=1.2.0
  
 
This method simply enables you to join a server via an URL with an already specified username and a password.
 
This method simply enables you to join a server via an URL with an already specified username and a password.
 +
 +
=== Server Password ===
 +
 +
To create a link to a server and specifying that servers password, you can leave the username empty.
 +
 +
mumble://:mypassword@server.com/?version=1.2.0
  
 
=== Channels ===
 
=== Channels ===
Line 70: Line 84:
 
Scheme:
 
Scheme:
  
  mumble://[USERNAME]:[PASSWORD]@[SERVER ADDRESS]:[PORT]/[CHANNEL]/[SUBCHANNEL]/[SUBSUBCHANNEL]/.../
+
  mumble://[USERNAME]:[PASSWORD]@[SERVER ADDRESS]:[PORT]/[CHANNEL]/[SUBCHANNEL]/[SUBSUBCHANNEL]/.../?version=1.2.0
  
 
Examples:
 
Examples:
  
  mumble://server.com/Root/Open%20Talk/Subchannel%20A/
+
  mumble://server.com/Open%20Talk/Subchannel%20A/Root/TestChannel/?version=1.2.0
  mumble://172.16.31.199/Root/TestChannel/
+
  mumble://172.16.31.199/TestChannel/?version=1.2.0
  mumble://server.com:23840/Root/Open%20Talk/Subchannel%20A/
+
  mumble://server.com:23840/Open%20Talk/Subchannel%20A/?version=1.2.0
  mumble://172.16.31.199:2000/Root/TestChannel/
+
  mumble://172.16.31.199:2000/TestChannel/?version=1.2.0
 
   
 
   
  mumble://TestUser@server.com/Root/Open%20Talk/Subchannel%20A/
+
  mumble://TestUser@server.com/Open%20Talk/Subchannel%20A/?version=1.2.0
  mumble://TheGimp@172.16.31.199/Root/TestChannel/
+
  mumble://TheGimp@172.16.31.199/TestChannel/?version=1.2.0
  mumble://TestUser@server.com:23840/Root/Open%20Talk/Subchannel%20A/
+
  mumble://TestUser@server.com:23840/Open%20Talk/Subchannel%20A/?version=1.2.0
  mumble://TheGimp@172.16.31.199:2000/Root/TestChannel/
+
  mumble://TheGimp@172.16.31.199:2000/TestChannel/?version=1.2.0
 
   
 
   
  mumble://TestUser:mypassword@server.com/Root/Open%20Talk/Subchannel%20A/
+
  mumble://TestUser:mypassword@server.com/Open%20Talk/Subchannel%20A/?version=1.2.0
  mumble://TheGimp:ilovezed@172.16.31.199/Root/TestChannel/
+
  mumble://TheGimp:ilovezed@172.16.31.199/TestChannel/?version=1.2.0
  mumble://TestUser:mypassword@server.com:23840/Root/Open%20Talk/Subchannel%20A/
+
  mumble://TestUser:mypassword@server.com:23840/Open%20Talk/Subchannel%20A/?version=1.2.0
  mumble://TheGimp:ilovezed@172.16.31.199:2000/Root/TestChannel/
+
  mumble://TheGimp:ilovezed@172.16.31.199:2000/TestChannel/?version=1.2.0
+
 
mumble://server.com/Open%20Talk/Subchannel%20A/Root/TestChannel/
+
This method enables you to join a server while specifying, in which channel you want to join. As you can see in the examples, you can combine this method with the methods described before. If your channel names contain whitespaces, you have to type "%20" instead of that whitespace.
mumble://172.16.31.199/TestChannel/
+
 
mumble://server.com:23840/Open%20Talk/Subchannel%20A/
+
== Special characters ==
mumble://172.16.31.199:2000/TestChannel/
+
 
+
If some other characters cause problems (like whitespaces), you have to use URL encoding on them. Simply get their hexadecimal number from an [http://en.wikipedia.org/wiki/Ascii_table#ASCII_printable_characters ASCII table] and replace the character with a "%" in front of it. For whitespace use %20.
  mumble://TestUser@server.com/Open%20Talk/Subchannel%20A/
+
 
mumble://TheGimp@172.16.31.199/TestChannel/
+
== URL Handler Installation ==
mumble://TestUser@server.com:23840/Open%20Talk/Subchannel%20A/
+
 
  mumble://TheGimp@172.16.31.199:2000/TestChannel/
+
If you have compiled Mumble from it's sources by yourself, the feature will not be available at first. You will have to register Mumble as a protocol handler for it's own URL type for your Desktop system in that case. If you installed Mumble with it's official installer, Mumble URLs should be accepted by your Desktop system, in that case, you can ignore this section.
+
 
mumble://TestUser:mypassword@server.com/Open%20Talk/Subchannel%20A/
+
=== Gnome ===
mumble://TheGimp:ilovezed@172.16.31.199/TestChannel/
+
 
mumble://TestUser:mypassword@server.com:23840/Open%20Talk/Subchannel%20A/
+
To enable Mumble URLs in the Gnome Desktop System on Linux, you have to execute the following commands:
mumble://TheGimp:ilovezed@172.16.31.199:2000/TestChannel/
+
 
 +
  gconftool-2 -s -t string /desktop/gnome/url-handlers/mumble/command 'mumble "%s"'
 +
  gconftool-2 -s -t bool /desktop/gnome/url-handlers/mumble/enabled true
 +
 
 +
If the "mumble" command is not globally accessible through the PATH environment variable, you must specify it's full path instead of the last "mumble" in the first of the two commands above.
 +
 
  
This method enables you to join a server while specifying, in which channel you want to join. As all Mumble servers contain a "Root" channel, you can choose if you want to type the root channel in your URL. As you can see in the examples, you can combine this method with the methods described before. If your channel name contain whitespaces, you have to type "%20" instead of that whitespace. If some other characters make problems, get it's hexadecimal number from an ASCII table and replace the character like the whitespace with a "%" in front of it.
+
[[Category:Documentation English]]

Latest revision as of 19:40, 23 October 2014

Mumble supports an own URL concept which enables you to join Mumble servers by a click of a link on a website, via links in the Mumble client (eg, in MOTD/chat messages, but only if AllowHTML is set to true), via links in your Desktop system or via the "Run" dialog of your system.

Mumble will also accept URLs as command line arguments:

Example:

mumble.exe mumble://server.com/?version=1.2.0

Beginning with 1.2.4, you can grab a URL to the current server/channel by right clicking the channel and selecting "Copy URL". Note that also beginning with 1.2.4, "?version" is not required, but it's still recommended that you include it as anyone who has 1.2.3 or earlier will launch the 1.1.x compatibility client when clicking links without "?version=1.2.0".

General URL

Mumble uses normal URLs with the "mumble" scheme.

mumble://[username[:password]@]<address>[:port]/[channelpath]?version=<serverversion>[&title=<servername>][&url=<serverurl>]

username and password are optional.

address is mandatory, and can be a IPv4 or IPv6 numerical address, or a hostname.

port is optional, and 64738 is the default if not specified.

channelpath is the path to the channel the client should try to move into. If the channel does not exist, the client will stay in the default channel.

serverversion is the protocol version of the server. This should be 1.1.0 for 1.1 servers, and 1.2.0 for 1.2. For the time being, 1.1.0 will be assumed if this parameter is missing, but once the majority of users have switched to the 1.2 release, the default will be 1.2.0 to make URLs shorter.

servername and serverurl are optional, and only used if the user drags the link and drops it in the server browser in Mumble. As this is a conventient way to add the server, we recommend they be filled out.

Remember to encode special characters with their % equivalent. Most URL classes will do this for you.

Simple Server Address

Scheme:

mumble://[SERVER ADDRESS]:[PORT]/?version=1.2.0

Examples:

mumble://server.com/?version=1.2.0
mumble://172.16.31.199/?version=1.2.0
mumble://server.com:23840/?version=1.2.0
mumble://172.16.31.199:2000/?version=1.2.0

This method simply enables you to join a server via an URL. Mumble will ask you instantly for your username and, if needed, for your password. As you can see in the examples, you are free to specify either an IP address or a DNS Name which represents the server you want to join. If the Mumble server does not listen on the default Mumble Port (64738), you can specify a port number after a separating colon.

Username

Scheme:

mumble://[USERNAME]@[SERVER ADDRESS]:[PORT]/?version=1.2.0

Examples:

mumble://TestUser@server.com/?version=1.2.0
mumble://TheGimp@172.16.31.199/?version=1.2.0
mumble://TestUser@server.com:23840/?version=1.2.0
mumble://TheGimp@172.16.31.199:2000/?version=1.2.0

This method simply enables you to join a server via an URL with an already specified username. Mumble will ask you instantly for your password, if this should be needed.

Username and Password

Scheme:

mumble://[USERNAME]:[PASSWORD]@[SERVER ADDRESS]:[PORT]/?version=1.2.0

Examples:

mumble://TestUser:mypassword@server.com/?version=1.2.0
mumble://TheGimp:ilovezed@172.16.31.199/?version=1.2.0
mumble://TestUser:mypassword@server.com:23840/?version=1.2.0
mumble://TheGimp:ilovezed@172.16.31.199:2000/?version=1.2.0

This method simply enables you to join a server via an URL with an already specified username and a password.

Server Password

To create a link to a server and specifying that servers password, you can leave the username empty.

mumble://:mypassword@server.com/?version=1.2.0

Channels

Scheme:

mumble://[USERNAME]:[PASSWORD]@[SERVER ADDRESS]:[PORT]/[CHANNEL]/[SUBCHANNEL]/[SUBSUBCHANNEL]/.../?version=1.2.0

Examples:

mumble://server.com/Open%20Talk/Subchannel%20A/Root/TestChannel/?version=1.2.0
mumble://172.16.31.199/TestChannel/?version=1.2.0
mumble://server.com:23840/Open%20Talk/Subchannel%20A/?version=1.2.0
mumble://172.16.31.199:2000/TestChannel/?version=1.2.0

mumble://TestUser@server.com/Open%20Talk/Subchannel%20A/?version=1.2.0
mumble://TheGimp@172.16.31.199/TestChannel/?version=1.2.0
mumble://TestUser@server.com:23840/Open%20Talk/Subchannel%20A/?version=1.2.0
mumble://TheGimp@172.16.31.199:2000/TestChannel/?version=1.2.0

mumble://TestUser:mypassword@server.com/Open%20Talk/Subchannel%20A/?version=1.2.0
mumble://TheGimp:ilovezed@172.16.31.199/TestChannel/?version=1.2.0
mumble://TestUser:mypassword@server.com:23840/Open%20Talk/Subchannel%20A/?version=1.2.0
mumble://TheGimp:ilovezed@172.16.31.199:2000/TestChannel/?version=1.2.0

This method enables you to join a server while specifying, in which channel you want to join. As you can see in the examples, you can combine this method with the methods described before. If your channel names contain whitespaces, you have to type "%20" instead of that whitespace.

Special characters

If some other characters cause problems (like whitespaces), you have to use URL encoding on them. Simply get their hexadecimal number from an ASCII table and replace the character with a "%" in front of it. For whitespace use %20.

URL Handler Installation

If you have compiled Mumble from it's sources by yourself, the feature will not be available at first. You will have to register Mumble as a protocol handler for it's own URL type for your Desktop system in that case. If you installed Mumble with it's official installer, Mumble URLs should be accepted by your Desktop system, in that case, you can ignore this section.

Gnome

To enable Mumble URLs in the Gnome Desktop System on Linux, you have to execute the following commands:

gconftool-2 -s -t string /desktop/gnome/url-handlers/mumble/command 'mumble "%s"'
gconftool-2 -s -t bool /desktop/gnome/url-handlers/mumble/enabled true

If the "mumble" command is not globally accessible through the PATH environment variable, you must specify it's full path instead of the last "mumble" in the first of the two commands above.