Difference between revisions of "Standards:MUD Client Media Protocol"

From Mudlet
Jump to navigation Jump to search
(Supporting Client.Media (https://github.com/Mudlet/Mudlet/pull/3132))
 
m (Client.Media.Play)
(13 intermediate revisions by the same user not shown)
Line 9: Line 9:
 
== Overview and Rationale ==
 
== Overview and Rationale ==
  
With renewed interest in the MUD genre of gaming, expectations are high to provide sight and sound content that competes for audience with other gaming platforms. The purpose of the MUD Client Media Protocol (MCMP) is to establish a method of delivering media, such as game sounds, background music and video snippets, to text-based game clients via their widely accepted messaging platform, GMCP, which uses JSON as its data-interchange format. The intended return for introducing this protocol is to improve the MUD gaming experience and accessibility through standardized messaging between game servers and game clients.  
+
With renewed interest in the MUD genre of gaming, expectations are high to provide sight and sound content that competes for audience with other gaming platforms. The purpose of the MUD Client Media Protocol (MCMP) is to establish a method of delivering media, such as game sounds, background music and video snippets, to text-based game clients via their widely accepted messaging platform, GMCP, which uses JSON as its data-interchange format. The intended return for introducing this protocol is to improve the MUD gaming experience and accessibility through standardized messaging between game servers and game clients. MUD Client Media Protocol (MCMP) is inspired by its predecessor [https://www.zuggsoft.com/zmud/msp.htm Mud Sound Protocol] (MSP).
  
 
== Overview of the GMCP (201) Sub-negotiation Protocol ==
 
== Overview of the GMCP (201) Sub-negotiation Protocol ==
Line 40: Line 40:
 
* Purpose: Identify to the game client a default URL directory to load media files an external resource.
 
* Purpose: Identify to the game client a default URL directory to load media files an external resource.
 
* Guidance: For games that automatically download media files, perform a Client.Media GMCP event once upon player login.
 
* Guidance: For games that automatically download media files, perform a Client.Media GMCP event once upon player login.
* Body: <syntaxhighlight lang="json">Client.Media {"url": "hxxps://www.example.com/media/"}</syntaxhighlight>
+
 
* Usage:
+
Syntax:
 +
<syntaxhighlight lang="json">Client.Media {"url": "hxxps://www.example.com/media/"}</syntaxhighlight>
 +
 
 +
Usage:
 
{| class="wikitable"
 
{| class="wikitable"
 
! Required
 
! Required
Line 55: Line 58:
 
|-
 
|-
 
|}
 
|}
 +
 +
{{note}} Some examples are shown [[Manual:Scripting#Loading_Media|here]].
  
 
==== Client.Media.Load ====
 
==== Client.Media.Load ====
Line 61: Line 66:
 
* Purpose: Load media files from an external source.
 
* Purpose: Load media files from an external source.
 
* Guidance: For games that automatically download media files and have the capability to cache with the game client.
 
* Guidance: For games that automatically download media files and have the capability to cache with the game client.
* Body: <syntaxhighlight lang="json">Client.Media.Load {
+
 
 +
Syntax:
 +
 
 +
<syntaxhighlight lang="json">Client.Media.Load {
 
   "name": "sword1.wav",
 
   "name": "sword1.wav",
 
   "url": "hxxps://www.example.com/media/",
 
   "url": "hxxps://www.example.com/media/",
 
   "tag": "combat"
 
   "tag": "combat"
 
}</syntaxhighlight>
 
}</syntaxhighlight>
* Usage:
+
 
 +
Usage:
 
{| class="wikitable"
 
{| class="wikitable"
 
! Required
 
! Required
Line 93: Line 102:
 
|-
 
|-
 
|}
 
|}
 +
 +
{{note}} Some examples are shown [[Manual:Scripting#Loading_Media|here]].
  
 
==== Client.Media.Play ====
 
==== Client.Media.Play ====
Line 99: Line 110:
 
* Purpose: Play media files.
 
* Purpose: Play media files.
 
* Guidance: Game clients could choose whether to play only one media file at one time or multiple files at one time.
 
* Guidance: Game clients could choose whether to play only one media file at one time or multiple files at one time.
* Body: <syntaxhighlight lang="json">Client.Media.Play {
+
 
 +
Syntax:
 +
<syntaxhighlight lang="json">Client.Media.Play {
 
   "name": "city.mp3",
 
   "name": "city.mp3",
 
   "url": "hxxps://www.example.com/media/",
 
   "url": "hxxps://www.example.com/media/",
Line 110: Line 123:
 
   "key": "area-background-music",
 
   "key": "area-background-music",
 
}</syntaxhighlight>
 
}</syntaxhighlight>
* Usage:
+
 
 +
Usage:
 
{| class="wikitable"
 
{| class="wikitable"
 
! Required
 
! Required
Line 187: Line 201:
 
|-
 
|-
 
|}
 
|}
 +
 +
{{note}} Some examples are shown [[Manual:Scripting#Playing_Media|here]].
  
 
==== Client.Media.Stop ====
 
==== Client.Media.Stop ====
Line 193: Line 209:
 
* Purpose: Stop playing media files.
 
* Purpose: Stop playing media files.
 
* Guidance: An empty body will stop all media.
 
* Guidance: An empty body will stop all media.
* Body: <syntaxhighlight lang="json">Client.Media.Stop {
+
 
 +
Syntax:
 +
<syntaxhighlight lang="json">Client.Media.Stop {
 
   "name": "city.mp3",
 
   "name": "city.mp3",
 
   "type": "music",
 
   "type": "music",
Line 200: Line 218:
 
   "key": "area-background-music",
 
   "key": "area-background-music",
 
}</syntaxhighlight>
 
}</syntaxhighlight>
* Usage:
+
 
 +
Usage:
 
{| class="wikitable"
 
{| class="wikitable"
 
! Required
 
! Required
Line 238: Line 257:
 
|-
 
|-
 
|}
 
|}
 +
 +
{{note}} Some examples are shown [[Manual:Scripting#Stopping_Media|here]].
  
 
== Authors ==
 
== Authors ==
Line 247: Line 268:
  
 
* Known clients implementing this specification:
 
* Known clients implementing this specification:
** Mudlet version 4.4+. See documentation.
+
** Mudlet version 4.4+. See [[Manual:Scripting#MUD_Client_Media_Protocol|documentation]].

Revision as of 00:49, 2 December 2019

MUD Client Media Protocol (MCMP)

A Standard for Loading, Playing and Stopping Media Files with MUD Clients over GMCP

Status of this Memo

This memo describes the addition of a standardized namespace of the Generic Mud Communication Protocol (GMCP) telnet sub-negotiation protocol (201) that provides syntax and usage guidance for sending JSON formatted messages from game servers to text-based game clients to load, play and stop media files.

Overview and Rationale

With renewed interest in the MUD genre of gaming, expectations are high to provide sight and sound content that competes for audience with other gaming platforms. The purpose of the MUD Client Media Protocol (MCMP) is to establish a method of delivering media, such as game sounds, background music and video snippets, to text-based game clients via their widely accepted messaging platform, GMCP, which uses JSON as its data-interchange format. The intended return for introducing this protocol is to improve the MUD gaming experience and accessibility through standardized messaging between game servers and game clients. MUD Client Media Protocol (MCMP) is inspired by its predecessor Mud Sound Protocol (MSP).

Overview of the GMCP (201) Sub-negotiation Protocol

To recap, the GMCP protocol is a bidirectional telnet sub-negotiation protocol (See RFC 854) which fulfills the following conditions:

  • GMCP is separated into several ‘namespaces’, which may be enabled or disabled by the client at any time. The ‘Core’ namespace is always enabled and may not be disabled. Namespaces should consist of case-insensitive alphabetical characters and stop characters (. - ASCII 46/0x2E), representable as [A-Za-z.].
  • GMCP messages consist of the namespace and a command (case insensitive alpha characters) delineated by a stop character, and optionally a space character and JSON-encoded payload.
  • GMCP messages may be sent by both the client or server at any time with no warning.

Update to namespace: Client.* for Client.Media

We are proposing an addition to the Client.* meta-namespace for Client.Media. This serves the purpose of reserving this namespace for handling game client media operations and supporting future expansion and integration.

Specification for Client.Media

The Client.Media family of GMCP packages provide a way for games to send sound, music and video events. GMCP media events are sent in one direction: from game server to to game client. Media files may be downloaded manually by the user and/or automatically via the game client. Game clients should advertise to servers that Client.Media is supported with a Core.Supports message from game client to server.

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

Note Note: Presenting game sound and music media content is the current focus. Presenting video content was also successfully tested with this specification.

Commands - Server

Client.Media

  • Package: Client.Media
  • Purpose: Identify to the game client a default URL directory to load media files an external resource.
  • Guidance: For games that automatically download media files, perform a Client.Media GMCP event once upon player login.

Syntax:

Client.Media {"url": "hxxps://www.example.com/media/"}

Usage:

Required Key Value Purpose
Yes "url" <url>
  • Resource location where the media file may be downloaded.

Note Note: Some examples are shown here.

Client.Media.Load

  • Package: Client.Media.Load
  • Purpose: Load media files from an external source.
  • Guidance: For games that automatically download media files and have the capability to cache with the game client.

Syntax:

Client.Media.Load {
  "name": "sword1.wav",
  "url": "hxxps://www.example.com/media/",
  "tag": "combat"
}

Usage:

Required Key Value Purpose
Yes "name" <file name>
  • Name of the media file.
Maybe "url" <url>
  • Resource location where the media file may be downloaded.
  • Only required if a url was not set with Client.Media.
No "tag" <tag>
  • Stores media in folders and helps categorize media.

Note Note: Some examples are shown here.

Client.Media.Play

  • Package: Client.Media.Play
  • Purpose: Play media files.
  • Guidance: Game clients could choose whether to play only one media file at one time or multiple files at one time.

Syntax:

Client.Media.Play {
  "name": "city.mp3",
  "url": "hxxps://www.example.com/media/",
  "type": "music",
  "tag": "environment",
  "volume": 25,
  "loops": 3,
  "priority": 60,
  "continue": true,
  "key": "area-background-music",
}

Usage:

Required Key Value Default Purpose
Yes "name" <file name>  
  • Name of the media file.
  • Wildcards * and ? may be used within the name to randomize media files selection.
Maybe "url" <url>  
  • Resource location where the media file may be downloaded.
  • Only required if the file is to be downloaded remotely and a url was not set above with Client.Media or Client.Media.Load.
No "type" "sound", "music" or "video" "sound"
  • Identifies the type of media.
No "tag" <tag>  
  • Stores media in folders and helps categorize media.
No "volume" 1 to 100 50
  • Relative to the volume set on the player's client.
No "loops" -1, or >= 1 1
  • Number of iterations that the media plays.
No "priority" 1 to 100  
  • Halts the play of current or future played media files with a lower priority while this media plays.
No "continue" true or false true
  • Only valid for media files with a "type" of "music".
  • Continues playing matching new music files when true
  • Restarts matching new music files when false.
No "key" <key>  
  • Uniquely identifies media files with a "key" that is bound to their "name" or "url".
  • Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.

Note Note: Some examples are shown here.

Client.Media.Stop

  • Package: Client.Media.Stop
  • Purpose: Stop playing media files.
  • Guidance: An empty body will stop all media.

Syntax:

Client.Media.Stop {
  "name": "city.mp3",
  "type": "music",
  "tag": "environment",
  "priority": 60,
  "key": "area-background-music",
}

Usage:

Required Key Value Purpose
No "name" <file name>
  • Stops playing media by name matching the value specified.
No "type" "sound", "music" or "video"
  • Stops playing media by type matching the value specified.
No "tag" <tag>
  • Stops playing media by tag matching the value specified.
No "priority" 1 to 100
  • Stops playing media with priority less than or equal to the value.
No "key" <key>
  • Stops playing media by key matching the value specified.

Note Note: Some examples are shown here.

Authors

  • Mike Conley (Co-Administrator at StickMUD and Mudlet contributor) sousesider[at]gmail.com
  • E--- O------- (Developer of ExVenture and Grapevine) e---[at]o-------.org

Notes

  • Known clients implementing this specification: