Linden Lab Official:Media Plugin System Messages

Media Rendering Plugin System

Overview

This article specifies the messages used by the Second Life Viewer media plugin system.

Arrows indicate which direction each message is sent:

> for host-to-plugin (or host-to-launcher shell for internal messages)

< for plugin-to-host.

Keys for each command are set off as bullet items, like this:

foo: a sample argument

Internal messages

Sent between the viewer and the launcher shell ONLY. Plugins will not need to handle these messages.

< hello: first command sent from the launcher shell to the viewer when it comes up
> load_plugin: tells the loader to load a plugin and send the base init message

file (string): the full path to the plugin DLL/dylib/so file.

< load_plugin_response: plugin loaded and initialized

versions (map): LLSD key/value map, where each key is a message class and its value is a version string. All versions start at "1.0".
plugin_version (string): Freeform version string for the plugin itself. This is expected to contain the versions of libraries the plugin uses (i.e. quicktime, webkit, etc.) and may end up in the viewer's about box.

< heartbeat: plugin launcher shell sends these once per second to show that the plugin isn't locked up
> shutdown: request an orderly shutdown
< shutdown_response: shutdown has completed, about to exit
> shm_add: shared memory segment has been set up in the parent

name (string)
size (S32)

< shm_add_response: shared memory has been mapped into the child

name (string)

> shm_remove: shared memory segment will be removed once you respond

name (string)

< shm_remove_response: plugin is done with the shared memory segment, safe to delete

name (string)

> sleep_time: set the interval between idle messages to the plugin

time (float): time in seconds (default is 1/100)

Base messages

All plugins need to handle these messages

> init
< init_response

versions (map): LLSD key/value map, where each key is a message class and its value is a version string.
- All versions start at "1.0".
- the host will need to check these against what it understands and send the proper versions of each message set to the plugin
plugin_version (string): Freeform version string for the plugin itself. This is expected to contain the versions of libraries the plugin uses (i.e. quicktime, webkit, etc.) and may end up in the viewer's about box.

> idle: call-in for plugin to do processing, no response

time (float): interval (in seconds) at which idle messages are being sent

> shutdown: request an orderly shutdown
< shutdown_response: completed cleanup, ready to be killed
> shm_added: shared memory segment has been set up

name (string)
size (S32)
address (string)
- Since this is going from the loader shell to the plugin (i.e. not crossing a process boundary), the pointer will actually be valid
- LLSD doesn't have an encoding for a pointer (or even an unsigned 32 bit value), so this will be the pointer's value as a hexadecimal string

> shm_remove: shared memory segment will be removed once you respond

name (string)

< shm_remove_response: plugin is done with the shared memory segment, safe to delete

name (string)

Media messages

< texture_params

default_width (S32) OPTIONAL -- default width for the texture
default_height (S32) OPTIONAL -- default height for the texture
depth (S32) -- pixel size in bytes
internalformat (U32) -- texture internalformat for glTexImage2D
format (U32) -- texture format for glTexImage2D
type (U32) -- texture type for glTexImage2D
swap_bytes(bool) OPTIONAL -- true if the host should use glPixelStorei(GL_UNPACK_SWAP_BYTES, 1) when loading the data
- if not specified, defaults to false.
coords_opengl(bool) -- true if the plugin wants to work in OpenGL coordinates (where (0,0) is the lower left corner of the texture), false to work in a coordinate system where (0,0) is the upper left
- Note that the hexadecimal GLenum values for these are fixed by the OpenGL ARB, so passing them across process boundaries should be safe
- Although the pixel size in bytes is completely determined by the format and type, deriving it from only those values is complex. To simplify things, the plugin must provide the pixel size to the host.
allow_downsample(bool) OPTIONAL -- If true, the host may negotiate a smaller texture when the plugin's priority is reduced.
- The plugin should not set this if downscaling the media is more expensive than drawing it at native size
padding(S32) OPTIONAL -- Specifies how the rows of the texture should be padded. Useful values:
- 0 (the default) -- no padding is added
- -1 -- pad width to the next power of two
- 16 -- start each row on a 16 byte boundary -- NOTE: may not work correctly with odd-sized pixels like GL_RGB
- 32 -- start each row on a 32 byte boundary -- NOTE: may not work correctly with odd-sized pixels like GL_RGB

> load_uri

uri (string)

> key_event

event (string) one of:
- down
- repeat
- up
key(S32) -- platform-specific keycode
modifiers -- string containing zero or more of the following, concatenated together with '|' characters in between. There may be a spurious trailing '|'.
- control
- alt -- means the 'option' key on the mac
- shift
- meta -- means the 'command' key on the mac

> text_event -- text input event not associated with a single keystroke

text(string) -- encoded in utf8

> mouse_event

event (string) : one of:
- down
- move
- up
- double_click
x -- x coordinate in texture space
y -- y coordinate in texture space (taking into account whether vertical flip was requested or not)
modifiers -- string containing zero or more of the following, concatenated together with '|' characters in between. There may be a spurious trailing '|'.
- control
- alt -- means the 'option' key on the mac
- shift
- meta -- means the 'command' key on the mac

> scroll_event: scrollwheel

x (integer) : horizontal scroll amount (positive or negative)
y (integer) : vertical scroll amount (positive or negative)
modifiers -- string containing zero or more of the following, concatenated together with '|' characters in between. There may be a spurious trailing '|'.
- control
- alt -- means the 'option' key on the mac
- shift
- meta -- means the 'command' key on the mac

< updated

left(S32)
top(S32)
right(S32)
bottom(S32)
current_time(float) OPTIONAL -- the current playhead time in seconds
duration(float) OPTIONAL -- the total duration of the media in seconds
current_rate(float) OPTIONAL -- the rate at which the media is currently playing

< media_status

status (string), one of:
- <empty string> -- not initialized or no media loaded
- loading -- loading or navigating
- loaded -- preroll/navigation complete
- error -- navigation/preroll failed
- playing -- playing (only for time-based media)
- paused -- paused (only for time-based media)

< size_change_request: when the stream wants to change its native size

width(S32)
height(S32)
name(string) -- the name of the shared memory segment the texture will draw into
- this may or may not induce the host to send a size_change message. The plugin may stop drawing to the texture until an appropriate size_change message has been received.

> size_change: either host-initiated or after a request from the plugin

width(S32)
height(S32)
texture_width(S32)
texture_height(S32)
name(string) -- the name of the shared memory segment the texture will draw into

< size_change_response: sent by the plugin when the size change is complete

width(S32)
height(S32)
texture_width(S32)
texture_height(S32)
name(string) -- the name of the shared memory segment the texture will draw into

< cursor_changed

name (string), one of:
- <empty string>
- arrow
- ibeam
- splith
- splitv
- hand

> set_priority: tells the plugin its relative priority

priority(string): one of:
- stopped: media is not playing, shouldn't need to update at all
- hidden: media is not being displayed or is out of view, don't need to do graphic updates, but may still update audio, playhead, etc.
- low: media is in the far distance, may be rendered at reduced size
- normal: default priority
- high: media has user focus and/or is taking up most of the screen

> edit_cut: do an edit-menu "cut" operation to the system clipboard
> edit_copy: do an edit-menu "copy" operation to the system clipboard
> edit_paste: do an edit-menu "paste" operation from the system clipboard
< edit_state: update the state of the edit menu items in the host

cut(bool) OPTIONAL
copy(bool) OPTIONAL
paste(bool) OPTIONAL
- items that are not present in the update message should have their state unchanged.
- All states start out false in the host.
- False means the operation is not possible and the menu should be disabled.

Media_browser messages

> focus

focused (bool): true if the browser instance has focus

> clear_cache
> clear_cookies
> enable_cookies

enable (bool)

> proxy_setup

enable (bool)
host (string)
port (S32)

> browse_stop
> browse_reload

ignore_cache(bool): if true, bypass cache for this reload

> browse_forward
> browse_back
> set_status_redirect (we use a 404 redirect in Web based search)

code(S32): the code to redirect on (should only be 404 for now)
url(string): the URL to redirect to

< navigate_begin

uri (string): uri the browser is navigating to

< navigate_complete

uri (string): uri the browser was navigating to
result_code (S32): 200, 404, etc.
result_string (string): "OK", "Not Found", etc.
history_back_available (bool): true if the "back" button should be enabled
history_forward_available (bool): true if the "forward" button should be enabled

< progress

percent (S32): percent of page load that has completed

< status_text

status (string): new browser status string

< location_changed

uri (string): new browser uri for the navigation bar

< click_href

uri (string): uri of the link
target (string): target property of the link

< click_nofollow

uri (string): uri of the link

> init_history

history (LLSD, array of strings): array of string URIs to add to the browser history

Media_time messages

> stop
> start

rate (float) OPTIONAL: rate to play at -- 0.0 is the movie's default rate, 1.0 is normal forward (on most movies), -1.0 is reverse, greater than 1.0 is fast foward, etc.

> pause
> seek

time (float)

> set_loop

loop (boolean): true to make the media loop, false to make it play once

> set_volume

volume (float)