libgpac
Documentation of the core library of GPAC
Loading...
Searching...
No Matches
Python APIs

Python API for libgpac. More...

Collaboration diagram for Python APIs:

Topics

 libgpac core tools
 Core tools for libgpac.
 HTTP server bindings
 Python API for libgpac httpout module.
 libgpac core tools
 FileIO tools for libgpac.

Data Structures

class  python.libgpac.libgpac.FilterTask
 Task object for user callbacks from libgpac scheduler. More...
class  python.libgpac.libgpac.FilterSession
 filter session object - see GF_FilterSession More...
class  python.libgpac.libgpac.Filter
 filter object More...
class  python.libgpac.libgpac.FilterCustom
 Base class used to create custom filters in python. More...
class  python.libgpac.libgpac.FilterPid
 Object representing a PID of a custom filter. More...
class  python.libgpac.libgpac.GLTextureInfo
 OpenGL texture info. More...
class  python.libgpac.libgpac.FilterPacket
 filter packet object More...

Detailed Description

Foreword

This module provides ctypes bindings for libgpac. These bindings currently allow:

  • initializing libgpac, setting global arguments for the library
  • creation, running and destruction of a filter session in blocking mode or non-blocking mode
  • inspection of filters in a session
  • user tasks scheduling
  • Creation of custom filters in Python
Note
This is an initial work and more bindings might be needed, feel free to contribute/PR on https://github.com/gpac/gpac

Error handling

Errors are handled through raising exceptions, except callback methods wich must return a GF_Err value.

Properties handling

Properties types are automatically converted to and from string. If the property name is not a built-in property type, the property is assumed to be a user-defined property. For example, when querying or setting a stream type property, use the property name StreamType. See gpac -h props for the complete list of built-in property names.

Properties values are automatically converted to or from python types whenever possible. Types with no python equivalent (vectors, fractions) are defined as classes in python. For example:

  • when setting a UIntList property, pass a python list of ints
  • when reading a UIntList property, a python list of ints will be returned
  • when setting a PropVec2i property, pass a PropVec2i object
  • when setting a PropVec2iList property, pass a python list of PropVec2i

4CCs are handled as strings in python, and list of 4CCs are handled as list of strings

The following builtin property types are always handled as strings in Python instead of int in libgpac :

  • StreamType: string containing the streamtype name
  • CodecID: string containing the codec name
  • Enumeration properties (PixelFormat, AudioFormat, ...): string containing the corresponding name

Basic setup

You can initialize libgpac before any other calls to set memory tracker or profile. When importing the module, libgpac is by default initialized with no memory tracking and using the default profile. You currently must uninintialize it after everything gpac-related is done. You also must destroy explicitly the filter session, as otherwise the garbage collection on the filter session object could happen after libgpac shutdown and will likely crash

import libgpac as gpac
gpac.init()
#create a session in blocking mode
fs = gpac.FilterSession()
#setup all your filters
...
#run the session
fs.run()
fs.delete()
gpac.close()

You can specify global options of libgpac and filters (e.g. –opt) by assigning arguments to libgpac:

#set global arguments, here inherited from command line
gpac.set_args(sys.argv)

You can also specify the log levels you want

gpac.set_logs("all@info")

Session using built-in filters

Filters are loaded as usual in gpac as a string description

src = fs.load_src("$URL:opt:opt2=val")
dst = fs.load_dst("$URL2:opt3:opt4=val")
f = fs.load("filtername:optX")

By default the filter session will run with implicit linking.

It is possible to assign sources of a filter (much like the @ command in gpac):

dst.set_source(f)

Posting user tasks

You can post tasks to the session scheduler to get called back (useful when running the session in blocking mode) Tasks must derive FilterTask class and implement their own execute method

class MyTask(FilterTask):
def exectute(self):
do_something()
#last scheduled task (session is over), abort
if self.session.last_task:
return -1
//keep task active, reschedule in 500 ms
return 500
task = MyTask('CustomTask')
fs.post_task(task)

Creating custom filters

A custom filter allows your application to interact closely with the media pipeline, but cannot be used in graph resolution. Custom filters can be sources, sinks, or intermediate filters. The following limitations however exist:

  • custom filters will not be cloned
  • custom filters cannot be used as sources of filters loading a source filter graph dynamically, such as the dashin filter.
  • custom filters cannot be used as destination of filters loading a destination filter graph dynamically, such as the dasher filters.

    A custom filter must implement the FilterCustom class, and optionally provide the following methods

    • configure_pid: callback for PID configuration, mandatory if your filter is not a source
    • process: callback for processing
    • process_event: callback for processing and event
    • probe_data: callback for probing a data format
    • reconfigure_output: callback for output reconfiguration (PID capability negotiation)

    A custom filter must also declare its capabilities, input and output, using push_cap method

    class MyFilter(FilterTask):
    def __init__(self, session):
    # !! call constructor of parent class first !!
    gpac.FilterCustom.__init__(self, session, "PYnspect")
    #indicate what we accept and produce - this can be done either in the constructor or after, but before calling \ref run or \ref run_step
    #here we indicate we accept anything of type visual, and produce anything of type visual
    self.push_cap("StreamType", "Visual", gpac.GF_CAPS_INPUT_OUTPUT)
    #we accept input pids, we must configure them
    #def configure_pid(self, pid, is_remove):
    #do something, return value is a GF_Err value
    #pid being removed
    if is_remove:
    #pid being reconfigured
    elif pid in self.ipids:
    #pid first connection
    else:
    #process
    #def process(self):
    #do something, return value is a GF_Err value
    #process_event takes a \ref FilterEvent parameter
    #def process_event(self, evt):
    #do something, return value is True (cancelled) or False
    #probe_data takes a NumPy array if numpy is available (and _size can be ignored) or a POINTER(c_ubyte) otherwise
    #def probe_data(self, data, _size):
    #do something, return value is mime type or None
    #probe_data takes the target output pid as parameter
    #def reconfigure_output(self, opid):
    #do something, return value is a GF_Err value
    Note
    The FilterCustom object has a list of input and output PIDs created. Before a callback to configure_pid, the input PID is not registered to the list of input PIDs if this is the first time the PID is configured.
    src = fs.load_src("$URL:opt:opt2=val")
    dst = fs.load_dst("$URL2:opt3:opt4=val")
    #load a custom filter
    my_filter = MyFilter(fs)
    #make sure dst only consumes from our custom filter
    dst.set_source(f)