Grapevine Sound GMCP Messages

sound.md

Migrated to an issue on Grapevine

oestrich/grapevine#117

GMCP Sound Protocol

Inspired by MSP

Enable Sound

The client will enable sound by including "Client.Sounds 1" as part of the initial Core.Supports messages.

Core.Supports.Set ["Client.Sounds 1", ...]

Play File

Send a Client.Sounds.Start event to start playing a sound or music file.

Client.Sounds.Start {
  "key": "zone-background-music",
  "url": "https://example.com/background.mp3",
  "type": "music",
  "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, URL to fetch the sound file at, this should be an mp3 or m4a
• type: optional, string, default "sound", options "music" or "sound"
• volume: optional, integer, 1-100, default 50, relative volume that the sound will play at
• loops: optional, integer, -1 or 1+, default 1, number of loops that the sound file should play before stopping, -1 continues until a stop event is sent
• continue: optional, boolean, default true, if true the sound file will continue playing if already playing, false will restart the sound
• priority: optional, integer, 1-100, default 50, if a higher priority sound comes in, all sounds of the same type under it will stop playing

Examples

Play a combat sound.

Client.Sounds.Start {
  "key": "combat",
  "url": "https://example.com/sword-swing.mp3"
}

Interrupt your sword swing with the enemy blocking.

Client.Sounds.Start {
  "key": "block",
  "url": "https://example.com/block.mp3",
  "priority": 51
}

Play zone background music.

Client.Sounds.Start {
  "key": "zone-background-music",
  "url": "https://example.com/background.mp3",
  "type": "music",
  "loops": -1,
  "continue": true
}

Migrate to a new zone.

Client.Sounds.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.Sounds.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.Sounds.Stop {
  "key": "storm"
}

Stop File

To stop a sound file that may be running, send an event with the specific key to stop.

Client.Sounds.Stop {
  "key": "zone-background-music"
}

To stop all sounds, send an event with no key.

Client.Sounds.Stop {}