Documentation of the core library of GPAC
JSFilter Interface Reference

JSFilter API. More...


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.

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.


◆ configure_pid()

attribute GF_Err JSFilter::configure_pid ( FilterPid  pid)

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

pidpid to (re)configure
error code if any

◆ remove_pid()

attribute GF_Err JSFilter::remove_pid ( FilterPid  pid)

removes an input pid See __gf_filter_register::configure_pid.

pidpid to remove
error code if any

◆ process()

attribute GF_Err JSFilter::process ( )

process See __gf_filter_register::process.

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.

pidpid on which the event is received
evtevent tp process
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.

arg_nameargument name
arg_valargument value
error code if any

◆ set_desc()

void JSFilter::set_desc ( DOMString  description)

sets filter desciption as visible when checking filter info

descriptiondescription of filter

◆ set_author()

void JSFilter::set_author ( DOMString  author)

sets filter author as visible when checking filter info

authorauthor of filter

◆ set_version()

void JSFilter::set_version ( DOMString  version)

sets filter version as visible when checking filter info

versionversion of filter

◆ set_help()

void JSFilter::set_help ( DOMString  help)

sets filter help as visible when checking filter info

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.

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.

cap_desccapability descriptor object

◆ set_name()

void JSFilter::set_name ( DOMString  name)

sets the name of the filter, used for logs

namethe filter name

◆ new_pid()

FilterPid JSFilter::new_pid ( )

creates a new PID - see gf_filter_pid_new

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

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

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
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

mimethe mime type to query
true if supported

◆ update_status()

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

update filter status string - see gf_filter_update_status

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

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

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

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

source_urlthe URL to check
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

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

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

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
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

destinationURL of destination to instantiate
mux_mimemime identifying destination format. If not set or null, format will be guessed from URL
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

argsname and arguments of the filter to load
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

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

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