Documentation of the core library of GPAC
Python APIs

Python API for using libgpac. More...

+ Collaboration diagram for Python APIs:


 libgpac core tools
 Core tools for libgpac.
 Structure Wrappers
 Python Structures.
 Constants definitions.
 DASH custom algorithm
 Python API 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.FilterPacket
 filter packet object More...

Detailed Description

Python API for libgpac.


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

This is an initial work and more bindings might be needed, feel free to contribute/PR on

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:

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 :

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
#create a session in blocking mode
fs = gpac.FilterSession()
#setup all your filters
#run the session

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

You can also specify the log levels you want


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


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):
#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')

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:

attribute JSFilterSession session
Definition: filtersession.idl:23