libgpac
Documentation of the core library of GPAC
JSFilter Interface Reference

JSFilter API. More...

import"jsf.idl";

Public Member Functions

attribute GF_Err initialize ()
 
attribute void finalize ()
 
attribute GF_Err configure_pid (FilterPid pid)
 
attribute GF_Err remove_pid (FilterPid pid)
 
attribute GF_Err process ()
 
attribute boolean process_event (FilterPid pid, FilterEvent evt)
 
attribute GF_Err update_arg (DOMString arg_name, DOMString arg_val)
 
void set_desc (DOMString description)
 
void set_author (DOMString author)
 
void set_version (DOMString version)
 
void set_help (DOMString help)
 
void set_arg (JSArgDesc arg)
 
void set_cap (optional JSCapDesc cap_desc=null)
 
void set_name (DOMString name)
 
FilterPid new_pid ()
 
void send_event (FilterEvent evt, optional boolean upstream=false)
 
FilterProperty get_info (DOMString info_name, optional boolean is_string=false)
 
boolean is_supported_mime (DOMString mime)
 
void update_status (DOMString status, optional long percent=0)
 
void reschedule (optional long reschedule_us=0)
 
void post_task (function task_callback, optional Object task_this=null)
 
void notify_failure (GF_Err error, optional long error_type=JSF_SETUP_ERROR)
 
boolean is_supported_source (DOMString source_url)
 
void hint_clock (unsigned long long time_in_microseconds, double media_time_sec)
 
void send_update (DOMString filter_id, DOMString arg_name, DOMString arg_value, long propagate_mask)
 
FilterInstance add_source (DOMString source, optional DOMString parent=null, optional boolean inherit_args=false)
 
FilterInstance add_destination (DOMString destination, optional DOMString mux_mime=null)
 
FilterInstance add_filter (DOMString args)
 
void make_sticky ()
 
void prevent_blocking (boolean do_prevent)
 
void block_eos (boolean do_block)
 

Data Fields

attribute long max_pids
 
readonly attribute boolean block_enabled
 
readonly attribute unsigned long output_buffer
 
readonly attribute unsigned long output_playout
 
readonly attribute DOMString sep_args
 
readonly attribute DOMString sep_name
 
readonly attribute DOMString sep_list
 
readonly attribute DOMString dst_args
 
readonly attribute DOMString dst_name
 
readonly attribute boolean sinks_done
 
attribute boolean reports_on
 
attribute unsigned long max_screen_width
 
attribute unsigned long max_screen_height
 
attribute unsigned long max_screen_depth
 
attribute unsigned long max_screen_fps
 
attribute unsigned long max_screen_views
 
attribute unsigned long max_audio_channels
 
attribute unsigned long max_audio_samplerate
 
attribute unsigned long max_audio_depth
 
readonly attribute unsigned long events_queued
 
readonly attribute unsigned long long readonly clock_hint_us
 
readonly attribute unsigned long long clock_hint_mediatime
 
readonly attribute unsigned long long connections_pending
 
attribute DOMString iname
 

Detailed Description

The JSFilter interface has a single instance exposed to the script under the name "filter". It implements binding to the underlying filter object, see GF_Filter. The JSFilter provides callback functions mapping the functionnalities of __gf_filter_register.

Member Function Documentation

◆ initialize()

attribute GF_Err JSFilter::initialize ( )

initialize the filter. This is a callback function assignable by the script. It is called once all filter arguments have been parsed. See __gf_filter_register::initialize.

Returns
error code if any

◆ finalize()

attribute void JSFilter::finalize ( )

finalize the filter. This is a callback function assignable by the script. It is called immediately before destruction of the JavaScript context. See __gf_filter_register::finalize.

Returns
void

◆ configure_pid()

attribute GF_Err JSFilter::configure_pid ( FilterPid  pid)

configures or reconfigures an input pid See __gf_filter_register::configure_pid.

Parameters
pidpid to (re)configure
Returns
error code if any

◆ remove_pid()

attribute GF_Err JSFilter::remove_pid ( FilterPid  pid)

removes an input pid See __gf_filter_register::configure_pid.

Parameters
pidpid to remove
Returns
error code if any

◆ process()

attribute GF_Err JSFilter::process ( )

process See __gf_filter_register::process.

Returns
error code if any

◆ process_event()

attribute boolean JSFilter::process_event ( FilterPid  pid,
FilterEvent  evt 
)

process an event on a given pid See __gf_filter_register::process_event.

Parameters
pidpid on which the event is received
evtevent tp process
Returns
error code if any

◆ update_arg()

attribute GF_Err JSFilter::update_arg ( DOMString  arg_name,
DOMString  arg_val 
)

process an event on a given pid See __gf_filter_register::process_event.

Parameters
arg_nameargument name
arg_valargument value
Returns
error code if any

◆ set_desc()

void JSFilter::set_desc ( DOMString  description)

sets filter desciption as visible when checking filter info

Parameters
descriptiondescription of filter

◆ set_author()

void JSFilter::set_author ( DOMString  author)

sets filter author as visible when checking filter info

Parameters
authorauthor of filter

◆ set_version()

void JSFilter::set_version ( DOMString  version)

sets filter version as visible when checking filter info

Parameters
versionversion of filter

◆ set_help()

void JSFilter::set_help ( DOMString  help)

sets filter help as visible when checking filter info

Parameters
helphelp of filter - can use the usual MarkDown syntax of GPAC help

◆ set_arg()

void JSFilter::set_arg ( JSArgDesc  arg)

adds an argument to the filter. JavaScript Filter arguments can be specified from command line in the same way as reguar filters. The argument is then exposed as a property of the "filter" object of the javascript context. If the argument name is a wildcard (*), the filter will be forwarded any argument name.

Parameters
argobject exposing the same interface as the JSArgDesc interface

◆ set_cap()

void JSFilter::set_cap ( optional JSCapDesc  cap_desc = null)

sets a new capability for the filter. If no argument, starts a new capability bundle.

Parameters
cap_desccapability descriptor object

◆ set_name()

void JSFilter::set_name ( DOMString  name)

sets the name of the filter, used for logs

Parameters
namethe filter name

◆ new_pid()

FilterPid JSFilter::new_pid ( )

creates a new PID - see gf_filter_pid_new

Returns
the new PID object

◆ send_event()

void JSFilter::send_event ( FilterEvent  evt,
optional boolean  upstream = false 
)

sends an event on the filter - see gf_filter_send_event

Parameters
evtthe event to send
upstreamsends the evnet upstream

◆ get_info()

FilterProperty JSFilter::get_info ( DOMString  info_name,
optional boolean  is_string = false 
)

queries info on a filter an event on the filter - see gf_filter_get_info and gf_filter_get_info_str

Parameters
info_namethe property name or ID of the info to query
is_stringindicate if the name describes a built-in property or a user-defined property
Returns
the property if found, null otherwise

◆ is_supported_mime()

boolean JSFilter::is_supported_mime ( DOMString  mime)

checks if a MIME type is supported - see gf_filter_is_supported_mime

Parameters
mimethe mime type to query
Returns
true if supported

◆ update_status()

void JSFilter::update_status ( DOMString  status,
optional long  percent = 0 
)

update filter status string - see gf_filter_update_status

Parameters
statusthe status string, may be null to reset the status string
percentpercent of processing, if known

◆ reschedule()

void JSFilter::reschedule ( optional long  reschedule_us = 0)

reschedule filter - see gf_filter_ask_rt_reschedule and gf_filter_post_process_task

Parameters
reschedule_usif not 0, reschedule the filter in the given amount of microseconds. Otherwise post a filter processing task

◆ post_task()

void JSFilter::post_task ( function  task_callback,
optional Object  task_this = null 
)

posts a task to the main scheduler - see gf_filter_post_task

Parameters
task_callbackthe callback function to use. This callback returns -1 or an exception to abort the task, or a reschedule time in milliseconds
task_thisoptional value for this object of the callback function. If not set, the filter object is used

◆ notify_failure()

void JSFilter::notify_failure ( GF_Err  error,
optional long  error_type = JSF_SETUP_ERROR 
)

notify a failure of the filter upon source connections - see gf_filter_notification_failure, gf_filter_notification_failure

Parameters
errorthe error code
error_typethe type of notification.

◆ is_supported_source()

boolean JSFilter::is_supported_source ( DOMString  source_url)

checks if a MIME type is supported - see gf_filter_is_supported_mime

Parameters
source_urlthe URL to check
Returns
true if supported

◆ hint_clock()

void JSFilter::hint_clock ( unsigned long long  time_in_microseconds,
double  media_time_sec 
)

checks if a MIME type is supported - see gf_filter_hint_single_clock

Parameters
time_in_microsecondstime in microseconds
media_time_secmedia timestamp inseconds

◆ send_update()

void JSFilter::send_update ( DOMString  filter_id,
DOMString  arg_name,
DOMString  arg_value,
long  propagate_mask 
)

sends an update to a filter - see gf_filter_send_update

Parameters
filter_idID of the filter
arg_namename of the argument
arg_valuevalue of the argument
propagate_maskpropagate mask

◆ add_source()

FilterInstance JSFilter::add_source ( DOMString  source,
optional DOMString  parent = null,
optional boolean  inherit_args = false 
)

adds a source filter in the media session - see gf_filter_connect_source

Parameters
sourceURL of source to load
parentURL of parent, used as baseURL for the source. May be NULL
inherit_argsif true, new filter will inherit arguments of this filter's destination
Returns
new loaded source filter or null

◆ add_destination()

FilterInstance JSFilter::add_destination ( DOMString  destination,
optional DOMString  mux_mime = null 
)

adds a destination filter in the media session - see gf_filter_connect_destination

Parameters
destinationURL of destination to instantiate
mux_mimemime identifying destination format. If not set or null, format will be guessed from URL
Returns
new loaded destination filter or null

◆ add_filter()

FilterInstance JSFilter::add_filter ( DOMString  args)

loads a new filter in the media session - see gf_filter_load_filter

Parameters
argsname and arguments of the filter to load
Returns
new loaded filter or null

◆ make_sticky()

void JSFilter::make_sticky ( )

makes the filter sticky - see gf_filter_make_sticky

◆ prevent_blocking()

void JSFilter::prevent_blocking ( boolean  do_prevent)

makes the filter unblocking - see gf_filter_prevent_blocking

Parameters
do_preventif true, filter will not be blocking if all its output pids are blocking

◆ block_eos()

void JSFilter::block_eos ( boolean  do_block)

makes the filter prevent EOS queries - see gf_filter_block_eos

Parameters
do_blockif true, filter input pids cannot be checked for end of stream during EOS queries

Field Documentation

◆ max_pids

attribute long JSFilter::max_pids

◆ block_enabled

readonly attribute boolean JSFilter::block_enabled

◆ output_buffer

readonly attribute unsigned long JSFilter::output_buffer

◆ output_playout

readonly attribute unsigned long JSFilter::output_playout

◆ sep_args

readonly attribute DOMString JSFilter::sep_args

◆ sep_name

readonly attribute DOMString JSFilter::sep_name

◆ sep_list

readonly attribute DOMString JSFilter::sep_list

◆ dst_args

readonly attribute DOMString JSFilter::dst_args

◆ dst_name

readonly attribute DOMString JSFilter::dst_name

◆ sinks_done

readonly attribute boolean JSFilter::sinks_done

◆ reports_on

attribute boolean JSFilter::reports_on

◆ max_screen_width

attribute unsigned long JSFilter::max_screen_width

◆ max_screen_height

attribute unsigned long JSFilter::max_screen_height

◆ max_screen_depth

attribute unsigned long JSFilter::max_screen_depth

◆ max_screen_fps

attribute unsigned long JSFilter::max_screen_fps

◆ max_screen_views

attribute unsigned long JSFilter::max_screen_views

◆ max_audio_channels

attribute unsigned long JSFilter::max_audio_channels

◆ max_audio_samplerate

attribute unsigned long JSFilter::max_audio_samplerate

◆ max_audio_depth

attribute unsigned long JSFilter::max_audio_depth

◆ events_queued

readonly attribute unsigned long JSFilter::events_queued

◆ clock_hint_us

readonly attribute unsigned long long readonly JSFilter::clock_hint_us

◆ clock_hint_mediatime

readonly attribute unsigned long long JSFilter::clock_hint_mediatime

◆ connections_pending

readonly attribute unsigned long long JSFilter::connections_pending

◆ iname

attribute DOMString JSFilter::iname

internal name - this can only be set and modified by JS API and allows for filter identification from JS