Python APIs

Python API for using libgpac. More...

Collaboration diagram for Python APIs:

Modules
	libgpac core tools
	Core tools for libgpac.
	Structure Wrappers
	Python Structures.
	Constants
	Constants definitions.
	HTTP server bindings
	Python API for libgpac httpout module.
	DASH custom algorithm
	Python API for libgpac DASH client.

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

Python API for libgpac.

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)