libgpac
Documentation of the core library of GPAC
Filter Session

Filter Session. More...

+ Collaboration diagram for Filter Session:

Data Structures

struct  GF_FilterStats
 

Macros

#define GF_FS_DEFAULT_SEPS   ":=#,!@"
 

Typedefs

typedef void(* gf_fs_on_filter_creation) (void *udta, GF_Filter *filter, Bool is_destroy)
 
typedef GF_Err(* gf_fs_gl_activate) (void *udta, Bool do_activate)
 

Enumerations

enum  GF_FilterSchedulerType {
  GF_FS_SCHEDULER_LOCK_FREE =0 , GF_FS_SCHEDULER_LOCK , GF_FS_SCHEDULER_LOCK_FREE_X , GF_FS_SCHEDULER_LOCK_FORCE ,
  GF_FS_SCHEDULER_DIRECT
}
 
enum  GF_FilterSessionFlags {
  GF_FS_FLAG_LOAD_META = 1<<1 , GF_FS_FLAG_NON_BLOCKING = 1<<2 , GF_FS_FLAG_NO_GRAPH_CACHE = 1<<3 , GF_FS_FLAG_NO_REGULATION = 1<<4 ,
  GF_FS_FLAG_NO_PROBE = 1<<5 , GF_FS_FLAG_NO_REASSIGN = 1<<6 , GF_FS_FLAG_PRINT_CONNECTIONS = 1<<7 , GF_FS_FLAG_NO_ARG_CHECK = 1<<8 ,
  GF_FS_FLAG_NO_RESERVOIR = 1<<9 , GF_FS_FLAG_FULL_LINK = 1<<10 , GF_FS_FLAG_NO_IMPLICIT = 1<<11 , GF_FS_FLAG_REQUIRE_SOURCE_ID = 1<<12 ,
  GF_FS_FLAG_FORCE_DEFER_LINK = 1<<13 , GF_FS_FLAG_PREVENT_PLAY = 1<<14
}
 
enum  GF_FSFlushType { GF_FS_FLUSH_NONE =0 , GF_FS_FLUSH_ALL , GF_FS_FLUSH_FAST }
 
enum  GF_FSFilterType {
  GF_FS_STATS_FILTER_GENERIC , GF_FS_STATS_FILTER_RAWIN , GF_FS_STATS_FILTER_DEMUX , GF_FS_STATS_FILTER_DECODE ,
  GF_FS_STATS_FILTER_ENCODE , GF_FS_STATS_FILTER_MUX , GF_FS_STATS_FILTER_RAWOUT , GF_FS_STATS_FILTER_MEDIA_SINK ,
  GF_FS_STATS_FILTER_MEDIA_SOURCE
}
 
enum  GF_EventPropagateType { GF_FILTER_UPDATE_DOWNSTREAM = 1 , GF_FILTER_UPDATE_UPSTREAM = 1<<1 }
 
enum  GF_SessionDebugFlag {
  GF_FS_DEBUG_GRAPH = 1 , GF_FS_DEBUG_STATS = 1<<1 , GF_FS_DEBUG_TASKS = 1<<2 , GF_FS_DEBUG_FILTERS = 1<<3 ,
  GF_FS_DEBUG_ALL = 0x00FFFFFF , GF_FS_DEBUG_CONTINUOUS = 0x80000000
}
 

Functions

GF_FilterSessiongf_fs_new (s32 nb_threads, GF_FilterSchedulerType type, GF_FilterSessionFlags flags, const char *blacklist)
 
GF_FilterSessiongf_fs_new_defaults (GF_FilterSessionFlags flags)
 
void gf_fs_del (GF_FilterSession *session)
 
GF_Filtergf_fs_load_filter (GF_FilterSession *session, const char *name, GF_Err *err_code)
 
Bool gf_fs_filter_exists (GF_FilterSession *session, const char *name)
 
GF_Err gf_fs_run (GF_FilterSession *session)
 
GF_Err gf_fs_set_separators (GF_FilterSession *session, const char *separator_set)
 
GF_Err gf_fs_set_max_resolution_chain_length (GF_FilterSession *session, u32 max_chain_length)
 
GF_Err gf_fs_set_max_sleep_time (GF_FilterSession *session, u32 max_sleep)
 
u32 gf_fs_get_max_resolution_chain_length (GF_FilterSession *session)
 
GF_Err gf_fs_stop (GF_FilterSession *session)
 
u32 gf_fs_filters_registers_count (GF_FilterSession *session)
 
const GF_FilterRegister * gf_fs_get_filter_register (GF_FilterSession *session, u32 idx)
 
void gf_fs_register_test_filters (GF_FilterSession *session)
 
GF_Filtergf_fs_load_source (GF_FilterSession *session, const char *url, const char *args, const char *parent_url, GF_Err *err)
 
GF_Filtergf_fs_load_destination (GF_FilterSession *session, const char *url, const char *args, const char *parent_url, GF_Err *err)
 
GF_Err gf_fs_get_last_connect_error (GF_FilterSession *session)
 
GF_Err gf_fs_get_last_process_error (GF_FilterSession *session)
 
void gf_fs_add_filter_register (GF_FilterSession *session, const GF_FilterRegister *freg)
 
void gf_fs_remove_filter_register (GF_FilterSession *session, GF_FilterRegister *freg)
 
void gf_fs_send_deferred_play (GF_FilterSession *session)
 
GF_Err gf_fs_post_user_task (GF_FilterSession *session, Bool(*task_execute)(GF_FilterSession *fsess, void *callback, u32 *reschedule_ms), void *udta_callback, const char *log_name)
 
GF_Err gf_fs_post_user_task_main (GF_FilterSession *session, Bool(*task_execute)(GF_FilterSession *fsess, void *callback, u32 *reschedule_ms), void *udta_callback, const char *log_name)
 
GF_Err gf_fs_abort (GF_FilterSession *session, GF_FSFlushType flush_type)
 
Bool gf_fs_is_last_task (GF_FilterSession *session)
 
Bool gf_fs_in_final_flush (GF_FilterSession *session)
 
Bool gf_fs_is_supported_mime (GF_FilterSession *session, const char *mime)
 
void gf_fs_set_ui_callback (GF_FilterSession *session, Bool(*ui_event_proc)(void *opaque, GF_Event *event), void *cbk_udta)
 
void gf_fs_print_stats (GF_FilterSession *session)
 
void gf_fs_print_connections (GF_FilterSession *session)
 
void gf_fs_print_non_connected (GF_FilterSession *session)
 
void gf_fs_print_non_connected_ex (GF_FilterSession *session, Bool ignore_sinks)
 
void gf_fs_print_unused_args (GF_FilterSession *session, const char *ignore_args)
 
void gf_fs_print_all_connections (GF_FilterSession *session, char *filter_name, void(*print_fn)(FILE *output, GF_SysPrintArgFlags flags, const char *fmt,...))
 
Bool gf_fs_check_filter_register_cap (const GF_FilterRegister *filter_reg, u32 in_cap_code, GF_PropertyValue *in_cap, u32 out_cap_code, GF_PropertyValue *out_cap, Bool exact_match_only)
 
void gf_fs_enable_reporting (GF_FilterSession *session, Bool reporting_on)
 
void gf_fs_lock_filters (GF_FilterSession *session, Bool do_lock)
 
u32 gf_fs_get_filters_count (GF_FilterSession *session)
 
GF_Filtergf_fs_get_filter (GF_FilterSession *session, u32 idx)
 
GF_Err gf_fs_get_filter_stats (GF_FilterSession *session, u32 idx, GF_FilterStats *stats)
 
Bool gf_fs_enum_unmapped_options (GF_FilterSession *session, u32 *idx, const char **argname, u32 *argtype, const char **meta_name, const char **meta_opt)
 
void gf_fs_send_update (GF_FilterSession *session, const char *fid, GF_Filter *filter, const char *name, const char *val, GF_EventPropagateType propagate_mask)
 
GF_Err gf_fs_load_script (GF_FilterSession *session, const char *jsfile)
 
u32 gf_fs_get_http_max_rate (GF_FilterSession *session)
 
GF_Err gf_fs_set_http_max_rate (GF_FilterSession *session, u32 rate)
 
u32 gf_fs_get_http_rate (GF_FilterSession *session)
 
Bool gf_fs_is_supported_source (GF_FilterSession *session, const char *url, const char *parent_url)
 
GF_Err gf_fs_set_filter_creation_callback (GF_FilterSession *session, gf_fs_on_filter_creation on_create_destroy, void *udta, Bool force_sync)
 
void * gf_fs_get_rt_udta (GF_FilterSession *session)
 
Bool gf_fs_check_filter (GF_FilterSession *session, GF_Filter *filter)
 
Bool gf_fs_fire_event (GF_FilterSession *session, GF_Filter *filter, GF_FilterEvent *evt, Bool upstream)
 
GF_Err gf_fs_set_external_gl_provider (GF_FilterSession *session, gf_fs_gl_activate on_gl_activate, void *udta)
 
void gf_fs_print_debug_info (GF_FilterSession *session, GF_SessionDebugFlag dbg_flags)
 

Detailed Description

The GPAC filter session object allows building media pipelines using multiple sources and destinations and arbitrary filter chains.

Filters are described through a __gf_filter_register structure. A set of built-in filters are available, and user-defined filters can be added or removed at runtime.

The filter session keeps an internal graph representation of all available filters and their possible input connections, which is used when resolving connections between filters.

The number of GF_FilterCapability matched between registries defines the weight of the connection.

Paths from an instantiated filter are enabled/disabled based on the source PID capabilities.

Paths to destination are recomputed for each destination, based on the instantiated destination filter capabilities.

The graph edges are then enabled in the possible subgraphs allowed by the destination capabilities, and unused filter registries (without enabled input connections) are removed from the graph.

The resulting weighted graph is then solved using Dijkstra's algorithm, using filter priority in case of weight equality.

The filter session works by default in a semi-blocking state. Whenever output PID buffers on a filter are all full, the filter is marked as blocked and not scheduled for processing. Whenever one output PID buffer is not full, the filter unblocks.

This implies that PID buffers may grow quite large if a filter is consuming data from a PID at a much faster rate than another filter consuming from that same PID.


Data Structure Documentation

◆ GF_FilterStats

struct GF_FilterStats

Filter statistics object

+ Collaboration diagram for GF_FilterStats:
Data Fields
const GF_Filter * filter

filter object

const GF_Filter * filter_alias

set if filter is only an alias, in which case all remaining fields of the structure are not set

u64 nb_tasks_done

number of tasks executed by this filter

u64 nb_pck_processed

number of packets processed by this filter

u64 nb_bytes_processed

number of bytes processed by this filter

u64 nb_pck_sent

number of packets sent by this filter

u64 nb_hw_pck_sent

number of hardware frames packets sent by this filter

u32 nb_errors

number of processing errors in the lifetime of the filter

u64 nb_bytes_sent

number of bytes sent by this filter

u64 time_process

number of microseconds this filter was active

s32 percent

percentage of data processed (between 0 and 100), otherwise unknown (-1)

const char * status

last status report from filter, null if session reporting is not enabled

Bool report_updated

set to GF_TRUE of status or percent changed since last query for this filter, GF_FALSE otherwise

const char * name

filter name

const char * reg_name

filter register name

const char * filter_id

filter register ID

Bool done

set to GF_TRUE if filter is done processing

u32 nb_pid_in

number of input PIDs

u64 nb_in_pck

number of input packets processed

u32 nb_pid_out

number of output PIDs

u64 nb_out_pck

number of output packets sent

Bool in_eos

set to GF_TRUE if filter has seen end of stream

GF_FSFilterType type

set to the filter class type

u32 stream_type

set to streamtype of output PID if single output, GF_STREAM_UNKNOWN otherwise

u32 codecid

set to codecid of output PID if single output, GF_CODECID_NONE otherwise

GF_Fraction64 last_ts_sent

timestamp and timescale of last packet emitted on output pids

GF_Fraction64 last_ts_drop

timestamp and timescale of last packet dropped on input pids

Macro Definition Documentation

◆ GF_FS_DEFAULT_SEPS

#define GF_FS_DEFAULT_SEPS   ":=#,!@"

The default separator set used

Typedef Documentation

◆ gf_fs_on_filter_creation

typedef void(* gf_fs_on_filter_creation) (void *udta, GF_Filter *filter, Bool is_destroy)

callback functions for external monitoring of filter creation or destruction

Parameters
udtauser data passed back to callback
filtercreated or destroyed filter
is_destroyif GF_TRUE, the filter is being destroyed, otherwise it is being created

◆ gf_fs_gl_activate

typedef GF_Err(* gf_fs_gl_activate) (void *udta, Bool do_activate)

callback functions for external monitoring of filter creation or destruction

Parameters
udtauser data passed back to callback
do_activateif true context must be activated for calling thread, otherwise context is no longer used
Returns
error if any

Enumeration Type Documentation

◆ GF_FilterSchedulerType

Filter session scheduler type

Enumerator
GF_FS_SCHEDULER_LOCK_FREE 

In this mode, the scheduler does not use locks for packet and property queues. Main task list is mutex-protected

GF_FS_SCHEDULER_LOCK 

In this mode, the scheduler uses locks for packet and property queues. Defaults to lock-free if no threads are used. Main task list is mutex-protected

GF_FS_SCHEDULER_LOCK_FREE_X 

In this mode, the scheduler does not use locks for packet and property queues, nor for the main task list

GF_FS_SCHEDULER_LOCK_FORCE 

In this mode, the scheduler uses locks for packet and property queues even if single-threaded (test mode)

GF_FS_SCHEDULER_DIRECT 

In this mode, the scheduler uses direct dispatch and no threads, trying to nest task calls within task calls

◆ GF_FilterSessionFlags

Filter session flags

Enumerator
GF_FS_FLAG_LOAD_META 

Flag set to indicate meta filters should be loaded. A meta filter is a filter providing various sub-filters. The sub-filters are usually not exposed as filters, only the parent one is. When set, all sub-filters are exposed. This should only be set when inspecting filters help

GF_FS_FLAG_NON_BLOCKING 

Flag set to run session in non-blocking mode. Each call to gf_fs_run will return as soon as there are no more pending tasks on the main thread

GF_FS_FLAG_NO_GRAPH_CACHE 

Flag set to disable internal caching of filter graph connections. If disabled, the graph will be recomputed at each link resolution (less memory occupancy but slower)

GF_FS_FLAG_NO_REGULATION 

Flag set to disable session regulation (no sleep)

GF_FS_FLAG_NO_PROBE 

Flag set to disable data probe

GF_FS_FLAG_NO_REASSIGN 

Flag set to disable source reassignment (e.g. switching from fin to ffdmx) in PID resolution

GF_FS_FLAG_PRINT_CONNECTIONS 

Flag set to print enabled/disabled edges for debug of PID resolution

GF_FS_FLAG_NO_ARG_CHECK 

Flag set to disable argument checking

GF_FS_FLAG_NO_RESERVOIR 

Disables reservoir for packets and properties, uses much less memory but much more alloc/free

GF_FS_FLAG_FULL_LINK 

Throws an error if any PID in the filter graph cannot be linked. The default behavior is to run the session even when some PIDs are not connected

GF_FS_FLAG_NO_IMPLICIT 

Flag set to disable implicit linking By default the session runs in implicit linking when no link directives are set on any filter: linking aborts after the first successful pid if destination is not a sink, or links only to sinks otherwise.

Note
This implies that the order in which filters are added to the session matters
GF_FS_FLAG_REQUIRE_SOURCE_ID 

Flag set to force all filters to require a source ID (same as setting RSID option on all filters). This is typically used when the app sets links on all used filters while declaring more, unused filters.

GF_FS_FLAG_FORCE_DEFER_LINK 

Flag set to force all explicitly added filters to be loaded in deferred link state - linking will only happen once gf_filter_reconnect_output is called on the filter.

GF_FS_FLAG_PREVENT_PLAY 

Flag set to ignore all PLAY events from sinks - use gf_fs_send_deferred_play to start playback

◆ GF_FSFlushType

Session flush types

Enumerator
GF_FS_FLUSH_NONE 

Do not flush session: everything is discarded, potentially breaking output files

GF_FS_FLUSH_ALL 

Flush all pending data before closing sessions: sources will be forced into end of stream and all emitted packets will be processed

GF_FS_FLUSH_FAST 

Stop session (resetting buffers) and flush pipeline

◆ GF_FSFilterType

Type of filter

Enumerator
GF_FS_STATS_FILTER_GENERIC 

Generic filter type accepting input(s) and producing output(s)

GF_FS_STATS_FILTER_RAWIN 

raw input (file, socket, pipe) filter type

GF_FS_STATS_FILTER_DEMUX 

demultiplexer filter type

GF_FS_STATS_FILTER_DECODE 

decoder filter type

GF_FS_STATS_FILTER_ENCODE 

encoder filter type

GF_FS_STATS_FILTER_MUX 

multiplexer filter type

GF_FS_STATS_FILTER_RAWOUT 

raw output (file, socket, pipe) filter type

GF_FS_STATS_FILTER_MEDIA_SINK 

media sink (video out, audio out, ...) filter type

GF_FS_STATS_FILTER_MEDIA_SOURCE 

media source (capture audio or video ...) filter type

◆ GF_EventPropagateType

Flags for argument update event

Enumerator
GF_FILTER_UPDATE_DOWNSTREAM 

the update event can be sent down the source chain

GF_FILTER_UPDATE_UPSTREAM 

the update event can be sent up the filter chain

◆ GF_SessionDebugFlag

Flags for debug info

Enumerator
GF_FS_DEBUG_GRAPH 

print filter graph

GF_FS_DEBUG_STATS 

print filter stats

GF_FS_DEBUG_TASKS 

print tasks present in scheduler

GF_FS_DEBUG_FILTERS 

print filter status and task scheduled on filter

GF_FS_DEBUG_ALL 

print all info

GF_FS_DEBUG_CONTINUOUS 

enable continuous reporting

Function Documentation

◆ gf_fs_new()

GF_FilterSession* gf_fs_new ( s32  nb_threads,
GF_FilterSchedulerType  type,
GF_FilterSessionFlags  flags,
const char *  blacklist 
)

Creates a new filter session. This will also load all available filter registers not blacklisted.

Parameters
nb_threadsnumber of extra threads to allocate. A negative value means all core used by session (eg nb_cores-1 extra threads)
typescheduler type
flagsset of above flags for the session. Modes set by flags cannot be changed at runtime
blackliststring containing comma-separated names of filters to disable. If first character is '-', this describes a whitelist, i.e. only filters listed in this string will be allowed
Returns
the created filter session

◆ gf_fs_new_defaults()

GF_FilterSession* gf_fs_new_defaults ( GF_FilterSessionFlags  flags)

Creates a new filter session, loading parameters from gpac config. This will also load all available filter registers not blacklisted.

Parameters
flagsset of flags for the session. Only GF_FS_FLAG_LOAD_META, GF_FS_FLAG_NON_BLOCKING , GF_FS_FLAG_NO_GRAPH_CACHE and GF_FS_FLAG_PRINT_CONNECTIONS are used, other flags are set from config file or command line
Returns
the created filter session

◆ gf_fs_del()

void gf_fs_del ( GF_FilterSession session)

Destructs the filter session

Parameters
sessionthe filter session to destruct

◆ gf_fs_load_filter()

GF_Filter* gf_fs_load_filter ( GF_FilterSession session,
const char *  name,
GF_Err err_code 
)

Loads a given filter by its register name. Filter are created using their register name, with options appended as a list of colon-separated Name=Value pairs. Value can be omitted for boolean, defaulting to true (eg :allt). Using '!' before the name negates the result (eg :!moof_first). Name can be omitted for enumerations (eg :disp=pbo is equivalent to :pbo), provided that filter developers pay attention to not reuse enum names in one filter.

Options are either options for the target filter class, options to be inherited between the new filter and its implicit source(s) or implici destination(s), or generic filter options.

Generic filter options are:

  • FID: filter identifier (string value)
  • SID: filter source(s) (string value)
  • N=NAME: filter name (string value)
  • FS: sub-session identifier (unsigned int value)
  • RSID: require sourceID to be present on target filters (no value)
  • TAG: filter tag (string value)
  • ITAG: filter inherited tag (string value)
  • FBT: buffer time in microseconds (unsigned int value)
  • FBU: buffer units (unsigned int value)
  • FBD: decode buffer time in microseconds (unsigned int value)
  • clone: explicitly enable/disable filter cloning flag (no value)
  • nomux: enable/disable direct file copy (no value)
  • gfreg: preferred filter registry names for link solving (string value)
  • gfloc: following options are local to filter declaration, not inherited (no value)
  • gfopt: following options are not tracked (no value)
  • gpac: argument separator for URLs (no value)
  • ccp: filter replacement control (string list value)
  • NCID: ID of netcap configuration to use (string)
  • DBG: debug missing input PID property (=pid), missing input packet property (=pck) or both (=all)
  • DL: enable defer linking of filter (no value) - the filter output pids will not be connected until a call to gf_filter_reconnect_output
Parameters
sessionfilter session
namename and arguments of the filter register to instantiate.
err_codeset to error code if any - may be NULL. If initially set to GF_EOS, disables log messages.
Returns
created filter or NULL if filter register cannot be found

◆ gf_fs_filter_exists()

Bool gf_fs_filter_exists ( GF_FilterSession session,
const char *  name 
)

Checks if a filter register exists by name.

Parameters
sessionfilter session
namename of the filter register to check.
Returns
GF_TRUE if a filter register exists with the given name, GF_FALSE otherwise

◆ gf_fs_run()

GF_Err gf_fs_run ( GF_FilterSession session)

Runs the session

If the session is non-blocking (created with GF_FS_FLAG_NON_BLOCKING), process all tasks of oldest scheduled filter, process any pending PID connections and returns. Otherwise (session is blocking), runs until session is over or aborted.

Parameters
sessionfilter session
Returns
error if any, or GF_EOS. The last errors can be retrieved using gf_fs_get_last_connect_error and gf_fs_get_last_process_error

◆ gf_fs_set_separators()

GF_Err gf_fs_set_separators ( GF_FilterSession session,
const char *  separator_set 
)

Sets the set of separators to use when parsing args

Parameters
sessionfilter session
separator_setfilter session. The first char is used to separate argument names - default is ':' The second char, if present, is used to separate names and values - default is '=' The third char, if present, is used to separate fragments for PID sources - default is '#' The fourth char, if present, is used for list separators (sourceIDs, gfreg, ...) - default is ',' The fifth char, if present, is used for boolean negation - default is '!' The sixth char, if present, is used for LINK directives - default is '@'
Returns
error if any

◆ gf_fs_set_max_resolution_chain_length()

GF_Err gf_fs_set_max_resolution_chain_length ( GF_FilterSession session,
u32  max_chain_length 
)

Sets the maximum length of a filter chain dynamically loaded to solve connection between two filters

Parameters
sessionfilter session
max_chain_lengthsets maximum chain length when resolving filter links. Default value is 6 ([ in -> ] demux -> reframe -> decode -> encode -> reframe -> mux [ -> out ]) (filter chains loaded for adaptation (eg pixel format change, audio resample) are loaded after the link resolution) Setting the value to 0 disables dynamic link resolution. You will have to specify the entire chain manually
Returns
error if any

◆ gf_fs_set_max_sleep_time()

GF_Err gf_fs_set_max_sleep_time ( GF_FilterSession session,
u32  max_sleep 
)

Sets the maximum sleep time when postponing tasks.

Parameters
sessionfilter session
max_sleepmaximum sleep time in milliseconds. 0 means yield only.
Returns
error if any

◆ gf_fs_get_max_resolution_chain_length()

u32 gf_fs_get_max_resolution_chain_length ( GF_FilterSession session)

gets the maximum filter chain lengtG

Parameters
sessionfilter session
Returns
maximum chain length when resolving filter links.

◆ gf_fs_stop()

GF_Err gf_fs_stop ( GF_FilterSession session)

Stops the session, waiting for all additional threads to complete

Parameters
sessionfilter session
Returns
error if any

◆ gf_fs_filters_registers_count()

u32 gf_fs_filters_registers_count ( GF_FilterSession session)

Gets the number of available filter registries (not blacklisted)

Parameters
sessionfilter session
Returns
number of filter registries

◆ gf_fs_get_filter_register()

const GF_FilterRegister* gf_fs_get_filter_register ( GF_FilterSession session,
u32  idx 
)

Returns the register at the given index

Parameters
sessionfilter session
idxindex of register, from 0 to gf_fs_filters_registers_count
Returns
the register object, or NULL if index is out of bounds

◆ gf_fs_register_test_filters()

void gf_fs_register_test_filters ( GF_FilterSession session)

Registers the test filters used for unit tests

Parameters
sessionfilter session

◆ gf_fs_load_source()

GF_Filter* gf_fs_load_source ( GF_FilterSession session,
const char *  url,
const char *  args,
const char *  parent_url,
GF_Err err 
)

Loads a source filter from a URL and arguments

Parameters
sessionfilter session
urlURL of the source to load. Can be a local file name, a full path (/.., \...) or a full URL with scheme (eg http://, tcp://)
argsarguments for the filter, see gf_fs_load_filter - the arguments can also be set in the url, typycally using :gpac: option delimiter
parent_urlparent URL of the source, or NULL if none
errif not NULL, is set to error code if any
Returns
the filter loaded or NULL if error

◆ gf_fs_load_destination()

GF_Filter* gf_fs_load_destination ( GF_FilterSession session,
const char *  url,
const char *  args,
const char *  parent_url,
GF_Err err 
)

Loads a destination filter from a URL and arguments

Parameters
sessionfilter session
urlURL of the source to load. Can be a local file name, a full path (/.., \...) or a full URL with scheme (eg http://, tcp://)
argsarguments for the filter, see gf_fs_load_filter - the arguments can also be set in the url, typycally using :gpac: option delimiter
parent_urlparent URL of the source, or NULL if none
errif not NULL, is set to error code if any
Returns
the filter loaded or NULL if error

◆ gf_fs_get_last_connect_error()

GF_Err gf_fs_get_last_connect_error ( GF_FilterSession session)

Returns the last error which happened during a PID connection

Parameters
sessionfilter session
Returns
the error code if any

◆ gf_fs_get_last_process_error()

GF_Err gf_fs_get_last_process_error ( GF_FilterSession session)

Returns the last error which happened during a filter process

Parameters
sessionfilter session
Returns
the error code if any

◆ gf_fs_add_filter_register()

void gf_fs_add_filter_register ( GF_FilterSession session,
const GF_FilterRegister *  freg 
)

Adds a user-defined register to the session - the register is added regardless of the session blacklist

Parameters
sessionfilter session
fregfilter register to add

◆ gf_fs_remove_filter_register()

void gf_fs_remove_filter_register ( GF_FilterSession session,
GF_FilterRegister *  freg 
)

Removes a user-defined register from the session

Parameters
sessionfilter session
fregfilter register to remove

◆ gf_fs_send_deferred_play()

void gf_fs_send_deferred_play ( GF_FilterSession session)

Sends PLAY event on all sinks, ignored if GF_FS_FLAG_PREVENT_PLAY flag is not set

Parameters
sessionfilter session

◆ gf_fs_post_user_task()

GF_Err gf_fs_post_user_task ( GF_FilterSession session,
Bool(*)(GF_FilterSession *fsess, void *callback, u32 *reschedule_ms)  task_execute,
void *  udta_callback,
const char *  log_name 
)

Posts a user task to the session

Parameters
sessionfilter session
task_executethe callback function for the task. The callback can return:
  • GF_FALSE to cancel the task
  • GF_TRUE to reschedule the task, in which case the task will be rescheduled immediately or after reschedule_ms.
udta_callbackcallback user data passed back to the task_execute function
log_namelog name of the task. If NULL, default is "user_task"
Returns
the error code if any

◆ gf_fs_post_user_task_main()

GF_Err gf_fs_post_user_task_main ( GF_FilterSession session,
Bool(*)(GF_FilterSession *fsess, void *callback, u32 *reschedule_ms)  task_execute,
void *  udta_callback,
const char *  log_name 
)

Posts a user task to the session main thread only

Parameters
sessionfilter session
task_executethe callback function for the task. The callback can return:
  • GF_FALSE to cancel the task
  • GF_TRUE to reschedule the task, in which case the task will be rescheduled immediately or after reschedule_ms.
udta_callbackcallback user data passed back to the task_execute function
log_namelog name of the task. If NULL, default is "user_task"
Returns
the error code if any

◆ gf_fs_abort()

GF_Err gf_fs_abort ( GF_FilterSession session,
GF_FSFlushType  flush_type 
)

Aborts the session. This can be called within a callback task to stop the session. Do NOT use gf_fs_stop from within a user task callback, this will deadlock the session

Parameters
sessionfilter session
flush_typeflush method to use
Returns
the error code if any

◆ gf_fs_is_last_task()

Bool gf_fs_is_last_task ( GF_FilterSession session)

Checks if the session is processing its last task. This can be called within a callback task to check if this is the last task, in order to avoid rescheduling the task

Parameters
sessionfilter session
Returns
GF_TRUE if no more task, GF_FALSE otherwise

◆ gf_fs_in_final_flush()

Bool gf_fs_in_final_flush ( GF_FilterSession session)

Checks if the session is in its final flush state (shutdown)

Parameters
sessionfilter session
Returns
GF_TRUE if no session is aborting, GF_FALSE otherwise

◆ gf_fs_is_supported_mime()

Bool gf_fs_is_supported_mime ( GF_FilterSession session,
const char *  mime 
)

Checks if a given MIME type is supported as input

Parameters
sessionfilter session
mimeMIME type to query
Returns
GF_TRUE if MIME is supported

◆ gf_fs_set_ui_callback()

void gf_fs_set_ui_callback ( GF_FilterSession session,
Bool(*)(void *opaque, GF_Event *event)  ui_event_proc,
void *  cbk_udta 
)

Sets UI callback event

Parameters
sessionfilter session
ui_event_procthe event proc callback function. Its return value depends on the event type, usually 0
cbk_udtapointer passed back to callback

◆ gf_fs_print_stats()

void gf_fs_print_stats ( GF_FilterSession session)

Prints stats to logs using

LOG_APP@LOG_INFO
Parameters
sessionfilter session

◆ gf_fs_print_connections()

void gf_fs_print_connections ( GF_FilterSession session)

Prints connections between loaded filters in the session to logs using

LOG_APP@LOG_INFO
Parameters
sessionfilter session

◆ gf_fs_print_non_connected()

void gf_fs_print_non_connected ( GF_FilterSession session)

Prints the list of filters not connected using

LOG_APP@LOG_WARNING
Parameters
sessionfilter session

◆ gf_fs_print_non_connected_ex()

void gf_fs_print_non_connected_ex ( GF_FilterSession session,
Bool  ignore_sinks 
)

Prints the list of filters not connected using

LOG_APP@LOG_WARNING
Parameters
sessionfilter session
ignore_sinksif set, do not warn if some sinks are not connected (mostly used for playback cases)

◆ gf_fs_print_unused_args()

void gf_fs_print_unused_args ( GF_FilterSession session,
const char *  ignore_args 
)

Prints the list of arguments specified but not used by the filter session using

LOG_APP@LOG_WARNING
Note
This is simply a wrapper to gf_fs_enum_unmapped_options
Parameters
sessionfilter session
ignore_argsignore unused arguments if present in this comma-separated list - may be NULL

◆ gf_fs_print_all_connections()

void gf_fs_print_all_connections ( GF_FilterSession session,
char *  filter_name,
void(*)(FILE *output, GF_SysPrintArgFlags flags, const char *fmt,...)  print_fn 
)

Prints all possible connections between filter registries to logs using

LOG_APP@LOG_INFO
Parameters
sessionfilter session
filter_nameif not null, only prints input connection for this filter register
print_fnoptional callback function for print, otherwise print to stderr

◆ gf_fs_check_filter_register_cap()

Bool gf_fs_check_filter_register_cap ( const GF_FilterRegister *  filter_reg,
u32  in_cap_code,
GF_PropertyValue *  in_cap,
u32  out_cap_code,
GF_PropertyValue *  out_cap,
Bool  exact_match_only 
)

Checks the presence of an input capability and an output capability in a target register. The caps are matched only if they belong to the same bundle.

Parameters
filter_regfilter register to check
in_cap_codecapability code (property type) of input capability to check
in_capcapabiility value of input capability to check
out_cap_codecapability code (property type) of output capability to check
out_capcapability value of output capability to check
exact_match_onlyif true returns TRUE only if exact match (code and value), otherwise return TRUE if caps code are matched
Returns
GF_TRUE if filter register has such a match, GF_FALSE otherwise

◆ gf_fs_enable_reporting()

void gf_fs_enable_reporting ( GF_FilterSession session,
Bool  reporting_on 
)

Enables or disables filter reporting

Parameters
sessionfilter session
reporting_onif GF_TRUE, reporting will be enabled

◆ gf_fs_lock_filters()

void gf_fs_lock_filters ( GF_FilterSession session,
Bool  do_lock 
)

Locks global session mutex - mostly used to query filter reports and avoids concurrent destruction of a filter. When adding a filter in an already running session, the session must be locked if set_source is to be used.

Parameters
sessionfilter session
do_lockif GF_TRUE, session is locked, otherwise session is unlocked

◆ gf_fs_get_filters_count()

u32 gf_fs_get_filters_count ( GF_FilterSession session)

Gets number of active filters in the session

Parameters
sessionfilter session
Returns
number of active filters

◆ gf_fs_get_filter()

GF_Filter* gf_fs_get_filter ( GF_FilterSession session,
u32  idx 
)

Gets a filter by its current index in the session

Parameters
sessionfilter session
idxindex in the filter session
Returns
filter, or NULL if none found

◆ gf_fs_get_filter_stats()

GF_Err gf_fs_get_filter_stats ( GF_FilterSession session,
u32  idx,
GF_FilterStats stats 
)

Gets statistics for a given filter index in the session

Parameters
sessionfilter session
idxindex of filter to query
statsstatistics for filter
Returns
error code if any

◆ gf_fs_enum_unmapped_options()

Bool gf_fs_enum_unmapped_options ( GF_FilterSession session,
u32 idx,
const char **  argname,
u32 argtype,
const char **  meta_name,
const char **  meta_opt 
)

Enumerates filter and meta-filter arguments not matched in the session. All output parameters may be NULL.

Parameters
sessionfilter session
idxindex of argument to query, 0 being first argument; this value is automatically incremented
argnameset to argument name
argtypeset to argument type: 0 was a filter param (eg :arg=val), 1 was a global arg (eg –arg=val) and 2 was a global meta arg (eg -+arg=val)
meta_nameset to meta filter name if any (for local filter args only)
meta_optset to meta filter suboption name if any (for local filter args only)
Returns
GF_TRUE if success, GF_FALSE if nothing more to enumerate

◆ gf_fs_send_update()

void gf_fs_send_update ( GF_FilterSession session,
const char *  fid,
GF_Filter filter,
const char *  name,
const char *  val,
GF_EventPropagateType  propagate_mask 
)

Enumerates filter and meta-filter arguments not matched in the session

Parameters
sessionfilter session
fidID of filter on which to send the update, NULL if filter is set
filterfilter on which to send the update, NULL if fid is set
namename of filter option to update
valvalue of filter option to update
propagate_maskpropagation flags - 0 means no propagation

◆ gf_fs_load_script()

GF_Err gf_fs_load_script ( GF_FilterSession session,
const char *  jsfile 
)

Loads JS script for filter session

Parameters
sessionfilter session
jsfilepath to local JS script file to use
Returns
error if any

◆ gf_fs_get_http_max_rate()

u32 gf_fs_get_http_max_rate ( GF_FilterSession session)

get max download rate allowed by download manager

Parameters
sessionfilter session
Returns
max rate in bps

◆ gf_fs_set_http_max_rate()

GF_Err gf_fs_set_http_max_rate ( GF_FilterSession session,
u32  rate 
)

set max download rate allowed by download manager

Parameters
sessionfilter session
ratemax rate in bps
Returns
error if any

◆ gf_fs_get_http_rate()

u32 gf_fs_get_http_rate ( GF_FilterSession session)

get current download rate of download manager, all active resources together

Parameters
sessionfilter session
Returns
current rate in bps

◆ gf_fs_is_supported_source()

Bool gf_fs_is_supported_source ( GF_FilterSession session,
const char *  url,
const char *  parent_url 
)

check if a URL is likely to be supported

Parameters
sessionfilter session
urlthe URL to test
parent_urlthe parent URL
Returns
GF_TRUE if a filter for such a source could be loaded

◆ gf_fs_set_filter_creation_callback()

GF_Err gf_fs_set_filter_creation_callback ( GF_FilterSession session,
gf_fs_on_filter_creation  on_create_destroy,
void *  udta,
Bool  force_sync 
)

assign callbacks for filter creation and destruction monitoring

Parameters
sessionfilter session
on_create_destroyfilter creation/destruction callback, may be NULL
udtauser data for callbacks, may be NULL
force_syncexecute tasks involving filter creation/setup and user tasks on main thread
Returns
error if any

◆ gf_fs_get_rt_udta()

void* gf_fs_get_rt_udta ( GF_FilterSession session)

returns RT user data passed in gf_fs_set_filter_creation_callback

Parameters
sessionfilter session
Returns
udta user data, NULL if error or none

◆ gf_fs_check_filter()

Bool gf_fs_check_filter ( GF_FilterSession session,
GF_Filter filter 
)

Checks if a filter is still valid - typically used when not monitoring filter destruction at session level using gf_fs_set_filter_creation_callback

Parameters
sessionfilter session
filterfilter to check
Returns
GF_TRUE if filter is still valid until the next call to gf_fs_run, GF_FALSE otherwise

◆ gf_fs_fire_event()

Bool gf_fs_fire_event ( GF_FilterSession session,
GF_Filter filter,
GF_FilterEvent *  evt,
Bool  upstream 
)

Fires an event on filter

Parameters
sessionfilter session
filtertarget filter - if NULL, event will be executed on all filters. Otherwise, the event will be executed directly if its type is GF_FEVT_USER, and fired otherwise
evtevent to fire
upstreamif true, send event toward sinks, otherwise towards sources
Returns
GF_TRUE if event was sent, GF_FALSE otherwise

◆ gf_fs_set_external_gl_provider()

GF_Err gf_fs_set_external_gl_provider ( GF_FilterSession session,
gf_fs_gl_activate  on_gl_activate,
void *  udta 
)

assign callbacks for filter creation and destruction monitoring

Parameters
sessionfilter session
on_gl_activateopenGL context activation callback, must not be NULL
udtauser data for callbacks, may be NULL
Returns
error if any

◆ gf_fs_print_debug_info()

void gf_fs_print_debug_info ( GF_FilterSession session,
GF_SessionDebugFlag  dbg_flags 
)

prints session debug info on stderr

To turn on (resp.off) continous reporting, set (resp. unset) the flag GF_FS_DEBUG_CONTINUOUS. Continuous reporting is done in the main thread using the last flags provided

Parameters
sessionfilter session
dbg_flagsset of flags indicating what to print