GstPtpClock: GStreamer 1.0 Library Reference Manual

## GstPtpClock GstPtpClock — Special clock that synchronizes to a remote time provider via PTP (IEEE1588:2008). |

## Functions

gboolean | gst_ptp_init ()
void | gst_ptp_deinit ()
gboolean | gst_ptp_is_initialized ()
gboolean | gst_ptp_is_supported ()
GstClock * | gst_ptp_clock_new ()
gboolean | (*GstPtpStatisticsCallback) ()
gulong | gst_ptp_statistics_callback_add ()
void | gst_ptp_statistics_callback_remove ()

## Properties

guint | domain | Read / Write / Construct Only
guint64 | grandmaster-clock-id | Read
GstClock * | internal-clock | Read
guint64 | master-clock-id | Read

## Types and Values

#define | GST_PTP_CLOCK_ID_NONE
struct | GstPtpClock
#define | GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED
#define | GST_PTP_STATISTICS_NEW_DOMAIN_FOUND
#define | GST_PTP_STATISTICS_PATH_DELAY_MEASURED
#define | GST_PTP_STATISTICS_TIME_UPDATED

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstClock
                    ╰── GstSystemClock
                        ╰── GstPtpClock

## Includes

    #include <gst/net/net.h>

## Description

GstPtpClock implements a PTP (IEEE1588:2008) ordinary clock in slave-only mode, that allows a GStreamer pipeline to synchronize to a PTP network clock in some specific domain.

The PTP subsystem can be initialized with `gst_ptp_init()`, which then starts a helper process to do the actual communication via the PTP ports. This is required as PTP listens on ports < 1024 and thus requires special privileges. Once this helper process is started, the main process will synchronize to all PTP domains that are detected on the selected interfaces.

gst_ptp_clock_new() then allows to create a GstClock that provides the PTP time from a master clock inside a specific PTP domain. This clock will only return valid timestamps once the timestamps in the PTP domain are known. To check this, you can use `gst_clock_wait_for_sync()`, the GstClock::synced signal and `gst_clock_is_synced()`.

To gather statistics about the PTP clock synchronization, `gst_ptp_statistics_callback_add()` can be used. This gives the application the possibility to collect all kinds of statistics from the clock synchronization.

## Functions

### gst_ptp_init ()

    gboolean
    gst_ptp_init (guint64 clock_id,
                  gchar **interfaces);

Initialize the GStreamer PTP subsystem and create a PTP ordinary clock in slave-only mode for all domains on the given `interfaces` with the given `clock_id` .

If `clock_id` is `GST_PTP_CLOCK_ID_NONE`, a clock id is automatically generated from the MAC address of the first network interface.

This function is automatically called by `gst_ptp_clock_new()` with default parameters if it wasn't called before.

#### Parameters

clock_id | PTP clock id of this process' clock or `GST_PTP_CLOCK_ID_NONE` |
interfaces | network interfaces to run the clock on. | [transfer none][array zero-terminated=1][allow-none]

#### Returns

`TRUE` if the GStreamer PTP clock subsystem could be initialized.

Since: 1.6

### gst_ptp_deinit ()

    void
    gst_ptp_deinit (void);

Deinitialize the GStreamer PTP subsystem and stop the PTP clock. If there are any remaining GstPtpClock instances, they won't be further synchronized to the PTP network clock.

Since: 1.6

### gst_ptp_is_initialized ()

    gboolean
    gst_ptp_is_initialized (void);

Check if the GStreamer PTP clock subsystem is initialized.

#### Returns

`TRUE` if the GStreamer PTP clock subsystem is intialized.

Since: 1.6

### gst_ptp_is_supported ()

    gboolean
    gst_ptp_is_supported (void);

Check if PTP clocks are generally supported on this system, and if previous initializations did not fail.

#### Returns

`TRUE` if PTP clocks are generally supported on this system, and previous initializations did not fail.

Since: 1.6

### gst_ptp_clock_new ()

    GstClock *
    gst_ptp_clock_new (const gchar *name,
                       guint domain);

Creates a new PTP clock instance that exports the PTP time of the master clock in `domain` . This clock can be slaved to other clocks as needed.

If `gst_ptp_init()` was not called before, this will call `gst_ptp_init()` with default parameters.

This clock only returns valid timestamps after it received the first times from the PTP master clock on the network. Once this happens the GstPtpClock::internal-clock property will become non-NULL. You can check this with `gst_clock_wait_for_sync()`, the GstClock::synced signal and `gst_clock_is_synced()`.

#### Parameters

name | Name of the clock |
domain | PTP domain |

Since: 1.6

### GstPtpStatisticsCallback ()

    gboolean
    (*GstPtpStatisticsCallback) (guint8 domain,
                                 const GstStructure *stats,
                                 gpointer user_data);

The statistics can be the following structures:

GST_PTP_STATISTICS_NEW_DOMAIN_FOUND: "domain" G_TYPE_UINT The domain identifier of the domain "clock" GST_TYPE_CLOCK The internal clock that is slaved to the PTP domain

GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED: "domain" G_TYPE_UINT The domain identifier of the domain "master-clock-id" G_TYPE_UINT64 PTP clock identifier of the selected master clock "master-clock-port" G_TYPE_UINT PTP port number of the selected master clock "grandmaster-clock-id" G_TYPE_UINT64 PTP clock identifier of the grandmaster clock

GST_PTP_STATISTICS_PATH_DELAY_MEASURED: "domain" G_TYPE_UINT The domain identifier of the domain "mean-path-delay-avg" GST_TYPE_CLOCK_TIME Average mean path delay "mean-path-delay" GST_TYPE_CLOCK_TIME Latest mean path delay "delay-request-delay" GST_TYPE_CLOCK_TIME Delay of DELAY_REQ / DELAY_RESP messages

GST_PTP_STATISTICS_TIME_UPDATED: "domain" G_TYPE_UINT The domain identifier of the domain "mean-path-delay-avg" GST_TYPE_CLOCK_TIME Average mean path delay "local-time" GST_TYPE_CLOCK_TIME Local time that corresponds to ptp-time "ptp-time" GST_TYPE_CLOCK_TIME Newly measured PTP time at local-time "estimated-ptp-time" GST_TYPE_CLOCK_TIME Estimated PTP time based on previous measurements "discontinuity" G_TYPE_INT64 Difference between estimated and measured PTP time "synced" G_TYPE_BOOLEAN Currently synced to the remote clock "r-squared" G_TYPE_DOUBLE R² of clock estimation regression "internal-time" GST_TYPE_CLOCK_TIME Internal time clock parameter "external-time" GST_TYPE_CLOCK_TIME External time clock parameter "rate-num" G_TYPE_UINT64 Internal/external rate numerator "rate-den" G_TYPE_UINT64 Internal/external rate denominator "rate" G_TYPE_DOUBLE Internal/external rate

If `FALSE` is returned, the callback is removed and never called again.

#### Parameters

domain | PTP domain identifier |
stats | New statistics |
user_data | Data passed to `gst_ptp_statistics_callback_add()` |

### gst_ptp_statistics_callback_add ()

    gulong
    gst_ptp_statistics_callback_add (GstPtpStatisticsCallback callback,
                                     gpointer user_data,
                                     GDestroyNotify destroy_data);

Installs a new statistics callback for gathering PTP statistics. See GstPtpStatisticsCallback for a list of statistics that are provided.

#### Parameters

callback | GstPtpStatisticsCallback to call |
user_data | Data to pass to the callback |
destroy_data | GDestroyNotify to destroy the data |

#### Returns

Id for the callback that can be passed to `gst_ptp_statistics_callback_remove()`

Since: 1.6

### gst_ptp_statistics_callback_remove ()

    void
    gst_ptp_statistics_callback_remove (gulong id);

Removes a PTP statistics callback that was previously added with `gst_ptp_statistics_callback_add()`.

#### Parameters

id | Callback id to remove |

Since: 1.6

## Types and Values

### GST_PTP_CLOCK_ID_NONE

    #define GST_PTP_CLOCK_ID_NONE ((guint64) -1)

### struct GstPtpClock

    struct GstPtpClock;

Opaque GstPtpClock structure.

### GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED

    #define GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED "GstPtpStatisticsBestMasterClockSelected"

### GST_PTP_STATISTICS_NEW_DOMAIN_FOUND

    #define GST_PTP_STATISTICS_NEW_DOMAIN_FOUND           "GstPtpStatisticsNewDomainFound"

### GST_PTP_STATISTICS_PATH_DELAY_MEASURED

    #define GST_PTP_STATISTICS_PATH_DELAY_MEASURED        "GstPtpStatisticsPathDelayMeasured"

### GST_PTP_STATISTICS_TIME_UPDATED

    #define GST_PTP_STATISTICS_TIME_UPDATED               "GstPtpStatisticsTimeUpdated"

## Property Details

### The `“domain”` property

      “domain”                   guint

The PTP domain.

Flags: Read / Write / Construct Only

Allowed values: <= 255

Default value: 0

### The `“grandmaster-clock-id”` property

      “grandmaster-clock-id”     guint64

Grand Master Clock ID.

Flags: Read

Default value: 0

### The `“internal-clock”` property

      “internal-clock”           GstClock *

Internal clock.

Flags: Read

### The `“master-clock-id”` property

      “master-clock-id”          guint64

Master Clock ID.

Flags: Read

Default value: 0

## See Also

GstClock, GstNetClientClock, GstPipeline