swfdec.Player

swfdec.Player — Main playback object

Synopsis

class swfdec.Player(gobject.GObject):
    swfdec.Player(debugger=None)
def advance(msecs)
def get_alignment()
def get_audio()
def get_background_color()
def get_base_url()
def get_default_size()
def get_maximum_runtime()
def get_next_event()
def get_rate()
def get_scale_mode()
def get_scripting()
def get_size()
def get_url()
def get_variables()
def is_initialized()
def key_press(keycode, character)
def key_release(keycode, character)
def mouse_move(x, y)
def mouse_press(x, y, button)
def mouse_release(x, y, button)
def render(cr, x, y, width, height)
def render_audio(dest, start_offset, n_samples)
def set_alignment(color)
def set_background_color(color)
def set_base_url(url)
def set_maximum_runtime(msec)
def set_scale_mode(mode)
def set_scripting(scripting)
def set_size(width, height)
def set_url(url)
def set_variables(variables)

Ancestry

+-- gobject.GObject
    +-- swfdec.Player

swfdec.Player Properties

"alignment"Read/Writepoint of the screen to align the output to. Default value: swfdec.ALIGNMENT_CENTER
"background-color"Read/WriteARGB color used to draw the background. Default value: 4294967295
"base-url"Read/Writebase URL for creating new resource or None if not set yet.
"cache-size"Read/WriteMaximum cache size in bytes. Default value: 52428800
"default-height"Readdefault height of the movie. Default value: 0.
"default-width"Readdefault width of the movie. Default value: 0.
"height"Read/Writecurrent height of the movie. Allowed values: >= -1 Default value: -1.
"initialized"ReadTrue when the player has initialized its basic values. Default value: False
"loader-type"Read/Writetype to use for creating loaders.
"max-runtime"Read/Writemaximum time in msecs scripts may run in the player before aborting.
"mouse-cursor"ReadHow the mouse pointer should be presented. Default value: swfdec.MOUSE_CURSOR_NONE
"next-event"ReadHow many milliseconds until the next event or 0 when no event pending. Default value: 0
"rate"Readrate in frames per second. Allowed values: [0,256]. Default value: 0.
"scale-mode"Read/Writemethod used to scale the movie. Default value: swfdec.SCALE_SHOW_ALL.
"scripting"Read/Writeexternal scripting implementation.
"socket-type"Read/Writetype to use for creating sockets.
"start-time"Read/Writetime to use as the beginning time for this player.
"system"Read/Writeobject holding system information.
"url"ReadURL of resource currently played back or NULL if not set.
"variables"Read/Writevariables to use when setting the URL. Default value: None.
"width"Read/Writecurrent width of the movie. Allowed values: >= -1. Default value: -1.

swfdec.Player Signal Prototypes

"advance"

def callback(player, msecs, audio_samples, user_param, ...)

"audio-added"

def callback(player, audio, user_param, ...)

"audio-removed"

def callback(player, audio, user_param, ...)

"fscommand"

def callback(player, command, parameter, user_param, ...)

"handle-key"

def callback(player, key, pressed, returns, user_param, ...)

"handle-mouse"

def callback(player, x, y, button, user_param, ...)

"invalidate"

def callback(player, x, y, width, height, user_param, ...)

"launch"

def callback(player, url, target, user_param, ...)

"missing-plugins"

def callback(player, details, user_param, ...)

Description

A swfdec.Player is the main object used for playing back Flash files through Swfdec.

A player interacts with the outside world in a multitude of ways. The most important ones are described below.

Input is handled via the SwfdecLoader class. A swfdec.Loader is set on a new player using swfdec.Player.set_loader().

When the loader has provided enough data, you can start playing the file. This is done in steps by calling swfdec.Player.advance() preferrably as often as swfdec.Player.get_next_event() indicates. Or you can provide user input to the player by calling for example swfdec.Player.handle_mouse().

You can use swfdec.Player.render() to draw the current state of the player. After that, connect to the swfdec.Player::invalidate signal to be notified of changes.

Audio output is handled via the swfdec.Audio class. One swfdec.Audio object is created for every output using the swfdec.Player::audio-added signal.

Constructor

    swfdec.Player(debugger=None)

debugger :

A SwfdecAsDebugger to use for debugging this player or None.

Returns :

A new swfdec.Player

Creates a new swfdec.Player.

Methods

swfdec.Player.advance

    def advance(msecs)

msecs :

The number of milliseconds to advance.

Returns :

Actual number of milliseconds advanced.

Advances player by msecs or at most one event, whatever happens first in the player's timeline. You should make sure to call this function as often as swfdec.Player.get_next_event() indicates or your player will not appear smooth.

swfdec.Player.get_alignment

    def get_alignment()

Returns :

the current alignment.

Gets the alignment of the player. The alignment describes what point is used as the anchor for drawing the contents. See swfdec.Alignment for possible values.

swfdec.Player.get_audio

    def get_audio()

Returns :

A list of swfdec.Audio. You must not modify this list.

Returns a list of all currently active audio streams in swfdec.Player.

swfdec.Player.get_background_color

    def get_background_color()

Returns :

The background color as an ARGB value.

Gets the current background color. The color will be an ARGB-quad, with the MSB being the alpha value.

swfdec.Player.get_base_url

    def get_base_url()

Returns :

the base swfdec.URL for resolving relative links or None.

Gets the base URL that this player uses when resolving a relative URL. It is automatically set to the parent directory of the currently played back resource, but can be changed using swfdec.Player.set_base_url(). When no resource has been set on the player yet, None is returned.

swfdec.Player.get_default_size

    def get_default_size()

Returns :

A tuple containing the default size.

If the default size of the movie is initialized, fills in width and height with the size. Otherwise width and height are set to 0.

swfdec.Player.get_maximum_runtime

    def get_maximum_runtime()

Returns :

the maximum time in milliseconds that scripts are allowed to run or 0 for infinite.

Queries the given player for how long scripts may run. see swfdec.Player.set_maximum_runtime() for a longer discussion of this value.

swfdec.Player.get_next_event

    def get_next_event()

Returns :

number of milliseconds until next event or 0 if no outstanding event.

Queries how long to the next event. This is the next time when you should call swfdec.Player.advance() to forward to.

swfdec.Player.get_rate

    def get_rate()

Returns :

The framerate of this movie or 0 if it isn't known yet or the movie doesn't have a framerate.

Queries the framerate of this movie. This number specifies the number of frames that are supposed to pass per second. It is a multiple of 1/256. It is possible that the movie has no framerate if it does not display a Flash movie but an FLV video for example. This does not mean it will not change however.

swfdec.Player.get_scale_mode

    def get_scale_mode()

Returns :

the current scale mode.

Gets the currrent mode used for scaling the movie. See SwfdecScaleMode for the different modes.

swfdec.Player.get_scripting

    def get_scripting()

Returns :

the current scripting implementation used or None.

Gets the current scripting implementation in use. If no implementation is in use (the default), None is returned.

swfdec.Player.get_size

    def get_size()

Returns :

a tuple containing the width and height.

Gets the currently set image size. If the default width or height should be used, the width or height respectively is set to -1.

swfdec.Player.get_url

    def get_url()

Returns :

the swfdec.URL currently played back or None.

Gets the URL of the resource that is currently played back. If no URL has been set on the player yet, None is returned.

swfdec.Player.get_variables

    def get_variables()

Returns :

a string represetation of the current variables or None if none are set on the player.

Gets the initial variables for this player. See swfdec.Player.set_variables() for details about variables.

swfdec.Player.is_initialized

    def is_initialized()

Returns :

True if the basic values are known.

Determines if the player is initalized yet. An initialized player is able to provide basic values like width, height or rate. A player may not be initialized if the loader it was started with does not reference a Flash resources or it did not provide enough data yet. If a player is initialized, it will never be uninitialized again.

swfdec.Player.key_press

    def key_press(keycode, character)

keycode :

the key that was pressed

character :

UCS4 of the character that was inserted or 0 if none.

Returns :

True if the key press was handled by the player, False if it should be propagated further

Call this function to make the player react to a key press. Be sure to check that keycode transformations are done correctly. For a list of keycodes see FIXME.

swfdec.Player.key_release

    def key_release(keycode, character)

keycode :

the key that was pressed

character :

UCS4 of the character that was inserted or 0 if none.

Returns :

True if the key press was handled by the player, False if it should be propagated further

Call this function to make the player react to a key being released. See swfdec.Player.key_press() for details.

swfdec.Player.mouse_move

    def mouse_move(x, y)

x :

x coordinate of mouse.

y :

y coordinate of mouse.

Returns :

True if the mouse event was handled. False if the event should be propagated further. A mouse event may not be handled if the user clicked on a translucent area.

Updates the current mouse position. If the mouse has left the area of player, you should pass values outside the movie size for x and y. You will probably want to call swfdec.Player.advance() before to update the player to the correct time when calling this function.

swfdec.Player.mouse_press

    def mouse_press(x, y, button)

x :

x coordinate of mouse.

y :

y coordinate of mouse.

button :

number of the button that was pressed. Swfdec supports up to 32 buttons.

Returns :

True if the mouse event was handled. False if the event should be propagated further. A mouse event may not be handled if the user clicked on a translucent area.

Tells the player that the mouse button button was pressed at the given coordinate.

swfdec.Player.mouse_release

    def mouse_release(x, y, button)

x :

x coordinate of mouse.

y :

y coordinate of mouse.

button :

number of the button that was pressed. Swfdec supports up to 32 buttons.

Returns :

True if the mouse event was handled. False if the event should be propagated further. A mouse event may not be handled if the user clicked on a translucent area.

Tells the player that the mouse button button was released at the given coordinate.

swfdec.Player.render

    def render(cr, x, y, width, height)

cr :

cairo.Context() to render to.

x :

x coordinate of top left position to render.

y :

y coordinate of top left position to render.

width :

width of area to render or 0 for full width.

height :

height of area to render or 0 for full width.

Returns :

Renders the given area of the current frame to cr.

swfdec.Player.render_audio

    def render_audio(dest, start_offset, n_samples)

dest :

location to add audio signal to. The audio signal will be in 44100kHz signed 16bit stereo.

start_offset :

offset in samples at which to start rendering. The offset is calculated relative to the last iteration, so the value set by swfdec.Player.advance() is ignored.

n_samples :

amount of samples to render.

Renders the data for this frame into the given location. The data is added to dest, so you probably want to initialize dest to silence before calling this function.

swfdec.Player.set_alignment

    def set_alignment(alignment)

alignment :

swfdec.Alignment to set

Sets the alignment to align. For details about alignment, see swfdec.Player.get_alignment() and swfdec.Alignment.

swfdec.Player.set_background_color

    def set_background_color(color)

color :

New color to use as background color.

Sets a new background color as an ARGB value. To get transparency, set the value to 0. To get a black beackground, use 0xFF000000.

swfdec.Player.set_base_url

    def set_base_url(url)

url :

a swfdec.URL or None to reset to defaults

Sets the URL that will be used for resolving realtive links inside the player.

swfdec.Player.set_maximum_runtime

    def set_maximum_runtime(msecs)

msecs :

time in milliseconds that scripts are allowed to run or 0 for infinite

Sets the time that the player may use to let internal scripts run. If the Flash file that is currently played back does not manage to complete its scripts in the given time, it is aborted. You cannot continue the scripts at a later point in time. However, your application may become unresponsive and your users annoyed if they cannot interact with it for too long. To give a reference point, the Adobe Flash player usually sets this value to 10 seconds. Note that this time determines the maximum time calling swfdec.Player.advance() may take, even if it is called with a large value. Also note that this setting is ignored when running inside a debugger.

swfdec.Player.set_scale_mode

    def set_scale_mode(mode)

mode :

a SwfdecScaleMode.

Sets the currrent mode used for scaling the movie. See SwfdecScaleMode for the different modes.

swfdec.Player.set_scripting

    def set_scripting(scripting)

scripting :

the scripting implementation to use or None to disable scripting.

Sets the implementation to use for external scripting in the given player. Note that this is different from the internal script engine. See the SwfdecPlayerScripting paragraph for details about external scripting.

swfdec.Player.set_size

    def set_size(width, height)

width :

desired width of the movie or -1 for default.

height :

desired height of the movie or -1 for default.

Sets the image size to the given values. The image size is what the area that the player will render and advocate with scripts.

swfdec.Player.set_url

    def set_url(url)

url :

the url for the initial reference in this player.

Sets the url for the main data. This function may only be called once.

swfdec.Player.set_variables

    def set_variables(variables)

variables :

a string that is checked to be in 'application/x-www-form-urlencoded' syntax describing the arguments to set on the new player or None.

Sets the loader for the main data. This function may only be called if swfdec.Player.set_url() has not been called yet. If the variables are set and validate, they will be set as properties on the root movie.

Signals

The "advance" swfdec.Player Signal

    def callback(player, msecs, audio_samples, user_param, ...)

player :

The swfdec.Player.

msecs :

The amount of milliseconds the player will advance.

audio_samples :

Number of frames the audio is advanced (in 44100Hz steps).

user_param :

the first user parameter (if any) specified with the connect() method

... :

additional user parameters (if any)

The "advanced" signal is emitted when the player advances.

The "audio-added" swfdec.Player Signal

    def callback(player, audio, user_param, ...)

player :

The swfdec.Player.

audio :

The audio stream that was added.

user_param :

the first user parameter (if any) specified with the connect() method

... :

additional user parameters (if any)

The "audio-added" signal is emitted when a new audio stream was added to player.

The "audio-removed" swfdec.Player Signal

    def callback(player, audio, user_param, ...)

player :

The swfdec.Player.

audio :

The audio stream that was removed.

user_param :

the first user parameter (if any) specified with the connect() method

... :

additional user parameters (if any)

The "audio-added" signal is emitted when a audio stream was removed from player. The stream will have been added with the SwfdecPlayer::audio-added signal previously.

The "fscommand" swfdec.Player Signal

    def callback(player, command, parameter, user_param, ...)

player :

The swfdec.Player.

command :

the command to execute. This is a lower case string.

parameter :

parameter to pass to the command. The parameter depends on the function.

user_param :

the first user parameter (if any) specified with the connect() method

... :

additional user parameters (if any)

The "fscommand" signal is emitted when a Flash script command (also known as fscommand) is encountered. This method is ued by the Flash file to communicate with the hosting environment. In web browsers it is used to call Javascript functions. Standalone Flash players understand a limited set of functions. They vary from player to player, but the most common are listed here:"quit": quits the player. "fullscreen": A boolean setting (parameter is "true" or "false") that sets the player into fullscreen mode. "allowscale": A boolean setting that tells the player to not scale the Flash application. "showmenu": A boolean setting that tells the Flash player to not show its own entries in the right-click menu. "exec": Run an external executable. The parameter specifies the path. "trapallkeys": A boolean setting that tells the Flash player to pass all key events to the Flash application instead of using it for keyboard shortcuts or similar.

The "handle-mouse" swfdec.Player Signal

    def callback(player, key, pressed, returns, user_param, ...)

player :

The swfdec.Player.

key :

SwfdecKey that was pressed or released.

pressed :

True if the key was pressed or False if it was released

user_param :

the first user parameter (if any) specified with the connect() method

... :

additional user parameters (if any)

The "handle-key" signal is emitted when player should respond to a key event. If any of the handlers returns True, swfdec.Player.key_press() or swfdec.Player.key_release() will return True. Note that unlike many event handlers in gtk, returning True will not stop further event handlers from being invoked. Use g_signal_stop_emission() in that case.

The "handle-mouse" swfdec.Player Signal

    def callback(player, x, y, button, user_param, ...)

player :

The swfdec.Player.

x :

New x coordinate of the mouse.

y :

New y coordinate of the mouse.

button :

1 if the button is pressed, 0 if not.

user_param :

the first user parameter (if any) specified with the connect() method

... :

additional user parameters (if any)

The "handle-mouse" signal is emitted when player should respond to a mouse event. If any of the handlers returns True, handle_mouse will return True. Note that unlike many event handlers in gtk, returning True will not stop further event handlers from being invoked. Use gobject.signal_stop_emission() in that case.

The "invalidate" swfdec.Player Signal

    def callback(player, x, y, width, height, user_param, ...)

player :

The swfdec.Player.

x :

x coordinate of invalid region.

y :

y coordinate of invalid region.

width :

Width of invalid region.

height :

Height of invalid region.

user_param :

the first user parameter (if any) specified with the connect() method

... :

additional user parameters (if any)

The "invalidate" signal is emitted when graphical elements inside the player have changed. The coordinates describe the smallest rectangle that includes all changes.

The "launch" swfdec.Player Signal

    def callback(player, url, target, user_param, ...)

player :

The swfdec.Player.

url :

URL to open.

target :

Target to load the URL into.

user_param :

the first user parameter (if any) specified with the connect() method

... :

additional user parameters (if any)

The "launch" signal is emitted when the player encounters an URL that should be loaded into a target the Flash player does not recognize. In most cases this happens when the user clicks a link in an embedded Flash movie that should open a new web page. The effect of calling any swfdec functions on the emitting player is undefined.

The "trace" swfdec.Player Signal

    def callback(player, text, user_param, ...)

player :

The swfdec.Player.

text :

The debugging string.

user_param :

the first user parameter (if any) specified with the connect() method

... :

additional user parameters (if any)

The "trace" signal emits a debugging string while running. The effect of calling any swfdec functions on the emitting player is undefined.