grapevine
grapevine copied to clipboard
Play sound in the web client
MUD Client Media Protocol
Inspired by MSP
Enable Media
The client will enable sound by including "Client.Sounds 1"
as part of the initial Core.Supports
messages.
Core.Supports.Set ["Client.Media 1", ...]
Set Default Values
You can set the default values for certain other messages by sending this message.
Client.Media.Default {
"url": "https://www.example.com/sounds/"
}
- url: required, string, base URL to fetch the sound file at
Play File
Send a Client.Sounds.Start
event to start playing a sound or music file.
Client.Media.Start {
"key": "zone-background-music",
"url": "https://example.com/",
"name": background.mp3",
"type": "music",
"tag": "zones",
"volume": 100,
"loops": -1,
"continue": true,
"priority": 51
}
- key: required, string, this is a unique key that will identify the sound in future events
- url: required, string, base URL to fetch the sound file at
- name: required, string, file name to add to the base url above, this should be an mp3
-
type: optional, string, default
"sound"
, options"music"
or"sound"
- tag: optional, string, extra string to help tag sounds for internal organization
-
volume: optional, integer,
1-100
, default50
, relative volume that the sound will play at -
loops: optional, integer,
-1
or1+
, default1
, number of loops that the sound file should play before stopping,-1
continues until a stop event is sent -
continue: optional, boolean, default
true
, iftrue
the sound file will continue playing if already playing,false
will restart the sound -
priority: optional, integer,
1-100
, default50
, if a higher priority sound comes in, all sounds of the same type under it will stop playing
Stop File
To stop a media file that may be running, send an event with a filter to stop all matching media.
Client.Media.Stop {
"key": "zone-background-music",
"type": "music",
"priority": 50,
"tag": "zones",
"name": "background.mp3"
}
The filter above will check all active media files, and any matching media is stopped. For key, type, tag, and name, a simple string match is performed. For priority, anything below or equal to the sent value is matched.
Media must match all sent values in order to be considered a match and stopped.
To stop all sounds, send an event with no key.
Client.Media.Stop {}
Examples
Play a combat sound.
Client.Media.Start {
"key": "combat",
"url": "https://example.com/sword-swing.mp3"
}
Interrupt your sword swing with the enemy blocking.
Client.Media.Start {
"key": "block",
"url": "https://example.com/block.mp3",
"priority": 51
}
Play zone background music.
Client.Media.Start {
"key": "zone-background-music",
"url": "https://example.com/background.mp3",
"type": "music",
"loops": -1,
"continue": true
}
Migrate to a new zone.
Client.Media.Start {
"key": "zone-background-music",
"url": "https://example.com/background2.mp3",
"type": "music",
"loops": -1,
"continue": false
}
Continue playing the zone's background, but add in a passing storm.
Client.Media.Start {
"key": "storm",
"url": "https://example.com/background-storm.mp3",
"type": "music",
"loops": -1,
"continue": false
}
Stop the storm, the zone background will continue playing.
Client.Media.Stop {
"key": "storm"
}