libgpac
Documentation of the core library of GPAC
JSFilterSession Interface Reference

JSFilterSession API. More...

import"filtersession.idl";

Public Member Functions

JSFilterSession FilterSession ()
 
JSFilterSession FilterSession (JSFilterSessionConfig config)
 
void post_task (function task_callback, optional DOMString task_name=null)
 
void abort (optional unsigned long flush_type=0)
 
void lock_filters (boolean do_lock)
 
JSFSFilter get_filter (unsigned long index)
 
JSFSFilter get_filter (DOMString iname)
 
void enable_rmt ()
 
void rmt_send (DOMString command)
 
void set_rmt_fun (function callback)
 
JSFSFilter add_filter (DOMString filter_to_add, optional JSFSFilter link_from=null, optional DOMString link_args=null, optional boolean relative_to_script=false)
 
void remove_filter (Object filter)
 
void set_new_filter_fun (function callback)
 
void set_del_filter_fun (function callback)
 
void set_event_fun (function callback)
 
void set_auth_fun (function callback)
 
boolean fire_event (FilterEvent evt, optional JSFSFilter *filter=null, optional boolean upstream=false)
 
void reporting (boolean enable)
 
JSFilter new_filter (DOMString name=null)
 
Array filter_args (DOMString desciption)
 
void print_connections ()
 
void print_stats ()
 
long run ()
 
long stop ()
 
long abort (optional unsigned long flush_type)
 

Data Fields

attribute long nb_filters
 
readonly attribute boolean last_task
 
attribute unsigned long http_max_bitrate
 
readonly attribute unsigned long http_bitrate
 
readonly attribute boolean connected
 
readonly attribute boolean last_process_error
 
readonly attribute boolean last_connect_error
 
readonly attribute DOMString jspath
 

Detailed Description

The JSFilterSession interface has a single instance exposed to the script under the name "session". It implements binding to the underlying filter session object, see GF_FilterSession.

Member Function Documentation

◆ FilterSession() [1/2]

JSFilterSession JSFilterSession::FilterSession ( )

Constructor for creating a user-defined filter session

Returns
a filter session, created in blocking mode

◆ FilterSession() [2/2]

JSFilterSession JSFilterSession::FilterSession ( JSFilterSessionConfig  config)

Constructor for creating a user-defined filter session

Parameters
configconfiguration for session
Returns
a filter session

◆ post_task()

void JSFilterSession::post_task ( function  task_callback,
optional DOMString  task_name = null 
)

posts a task to the main scheduler - see gf_fs_post_user_task

Parameters
task_callbackthe callback function to use. This callback functions has no parameters, and returns false or an exception to abort the task, true to reschedule the task immediately or a reschedule time in milliseconds
task_nameoptional value giving a label for the task

◆ abort() [1/2]

void JSFilterSession::abort ( optional unsigned long  flush_type = 0)

aborts the filter session - see gf_fs_abort

Parameters
flush_typeif true, wait for all packets currently pending to be processed before closing the session

◆ lock_filters()

void JSFilterSession::lock_filters ( boolean  do_lock)

locks the filter session - see gf_fs_lock_filters. When the session is locked, tasks are suspended and filters cannot be destroyed. The session only needs to be locked when enumerating filters

Parameters
do_lockif true, locks the session, otherwise unlocks it

◆ get_filter() [1/2]

JSFSFilter JSFilterSession::get_filter ( unsigned long  index)

returns the JSFSFilter object for the given index.

Parameters
indexindex of filter to query. This index is only valid when session is locked
Returns
the filter object, null if none found

◆ get_filter() [2/2]

JSFSFilter JSFilterSession::get_filter ( DOMString  iname)

returns the JSFSFilter object for a given filter iname.

Parameters
inamethe iname of filter to query
Returns
the filter object, null if none found

◆ enable_rmt()

void JSFilterSession::enable_rmt ( )

enable remotery - this should be called as early as possible in the session

◆ rmt_send()

void JSFilterSession::rmt_send ( DOMString  command)

sends the given string to the remotery client(s)

Parameters
commandthe command to send
Returns
error code if any

◆ set_rmt_fun()

void JSFilterSession::set_rmt_fun ( function  callback)

sets callback function to use when processing remotery client request

Parameters
callbackthe callback function to call. This function takes one parameter which is the text being received
Returns
error code if any

◆ add_filter()

JSFSFilter JSFilterSession::add_filter ( DOMString  filter_to_add,
optional JSFSFilter  link_from = null,
optional DOMString  link_args = null,
optional boolean  relative_to_script = false 
)

inserts a filter in graph

Parameters
filter_to_addstring describin the filter to add, can be in the form "src=" for sources, "dst=" for sinks or regular string for filters.
link_fromfilter used as source for the created filters - see gf_filter_set_source
link_argsarguments for the link (used to assign new filter SID - see gf_filter_set_source
relative_to_scriptif false, URLs for source and sinks filters are relative to the current working directory, if true they are relative to the script path
Returns
new filter created

◆ remove_filter()

void JSFilterSession::remove_filter ( Object  filter)

removes a filter in the media session

Parameters
filterfilter object to remove, can be a JSFSFilter object (in this case, function is equivalent to JSFSFilter.remove) or a JSFilter object

◆ set_new_filter_fun()

void JSFilterSession::set_new_filter_fun ( function  callback)

sets callback function to get notifications upon each new filter creation.

Parameters
callbackcallback function - it is passed a single parameter, the filter object

◆ set_del_filter_fun()

void JSFilterSession::set_del_filter_fun ( function  callback)

sets callback function to get notifications upon each filter destruction.

Parameters
callbackthe callback function - it is passed a single parameter, the filter object

◆ set_event_fun()

void JSFilterSession::set_event_fun ( function  callback)

sets callback function to get events being sent back to application (see gf_fs_set_ui_callback).

Parameters
callbackcallback function - it is passed a single parameter set, an event instance of FilterEvent interface. The return value of the function should be as indicated for each event type

◆ set_auth_fun()

void JSFilterSession::set_auth_fun ( function  callback)

sets callback function to get authentication requests (see gf_fs_set_ui_callback).

Parameters
callbackcallback function - the function takes 5 parameters and no return value type:
  • server: name of server
  • user: username
  • pass: password if known
  • secure: boolean indicating if connection is secured (TLS)
  • auth_obj: object used to acknowledge authentication, with a single function done() taking up to 3 parameters: user, passord and boolean indicating if credentials should be stored. If user or password are not set, authentication fails

◆ fire_event()

boolean JSFilterSession::fire_event ( FilterEvent  evt,
optional JSFSFilter filter = null,
optional boolean  upstream = false 
)

fires a given event on all registered user event if no filter is specified, or on the filter

Parameters
evtthe event to send
filterthe filter to send the event to
upstreamif filter is not null, indicates whether the event shall be sent upstream (towards the sink) or downstream (towards the destination)
Returns
true if event was fired, false if no event target was found or if the filter is not an event target

◆ reporting()

void JSFilterSession::reporting ( boolean  enable)

enables session reporting - see gf_fs_enable_reporting.

Parameters
enableenables reporting if true

◆ new_filter()

JSFilter JSFilterSession::new_filter ( DOMString  name = null)

creates a new custom JS filter. This filter will share the same script context as the filter session script - see JSFilter

Note
A custom filter cannot use default arguments, and will not have the initialize callback function called.
Parameters
namename for the filter. Optional internal filter arguments may be set after the name, e.g. MyName:ITAG=test
Returns
new filter

◆ filter_args()

Array JSFilterSession::filter_args ( DOMString  desciption)

loads all arguments of of a filter description. This will load all arguments on meta filters (not visible otherwise)

Parameters
desciptiondescription for the filter. Sources can be specified using src=URL, sinks can be specified using dst=URL.
Returns
array of JSFSFilterArg

◆ print_connections()

void JSFilterSession::print_connections ( )

print graph for session

◆ print_stats()

void JSFilterSession::print_stats ( )

print stats for session

◆ run()

long JSFilterSession::run ( )

run a session, only valid for user-created sessions

Returns
error code if any

◆ stop()

long JSFilterSession::stop ( )

stop a session, only valid for user-created sessions

Returns
error code if any

◆ abort() [2/2]

long JSFilterSession::abort ( optional unsigned long  flush_type)

abort a session, only valid for user-created sessions

Parameters
flush_typeflush type, cf GF_FSFlushType
Returns
error code if any

Field Documentation

◆ nb_filters

attribute long JSFilterSession::nb_filters

number of filters in the session - see gf_fs_get_filters_count. This number is only valid when session is locked

◆ last_task

readonly attribute boolean JSFilterSession::last_task

check if the calling task is the last task in the session - see gf_fs_is_last_task

◆ http_max_bitrate

attribute unsigned long JSFilterSession::http_max_bitrate

max capped HTTP download rate in bps - used for DASH simulations mostly

◆ http_bitrate

readonly attribute unsigned long JSFilterSession::http_bitrate

current http download rate averaged on all active resources in bps

◆ connected

readonly attribute boolean JSFilterSession::connected

set to true if no PID initialization task (connections) is pending

◆ last_process_error

readonly attribute boolean JSFilterSession::last_process_error

last process error, cf gf_fs_get_last_process_error

◆ last_connect_error

readonly attribute boolean JSFilterSession::last_connect_error

last connection error, cf gf_fs_get_last_connect_error

◆ jspath

readonly attribute DOMString JSFilterSession::jspath

File path of source script