## PtPlayer

PtPlayer — The GStreamer backend for Parlatype.

## Stability Level

Stable, unless otherwise indicated

## Functions

PtPlayer * | pt_player_new ()
void | pt_player_set_mode ()
PtModeType | pt_player_get_mode ()
gboolean | pt_player_configure_asr ()
gboolean | pt_player_config_is_loadable ()
gboolean | pt_player_open_uri ()
void | pt_player_play ()
void | pt_player_play_pause ()
void | pt_player_pause ()
void | pt_player_pause_and_rewind ()
gint | pt_player_get_pause ()
PtMediaInfo * | pt_player_get_media_info ()
void | pt_player_connect_waveviewer ()
void | pt_player_set_selection ()
void | pt_player_clear_selection ()
gboolean | pt_player_has_selection ()
void | pt_player_jump_relative ()
void | pt_player_jump_back ()
void | pt_player_jump_forward ()
gint | pt_player_get_back ()
gint | pt_player_get_forward ()
void | pt_player_jump_to_position ()
gdouble | pt_player_get_speed ()
void | pt_player_set_speed ()
gdouble | pt_player_get_volume ()
void | pt_player_set_volume ()
gboolean | pt_player_get_mute ()
void | pt_player_set_mute ()
gint64 | pt_player_get_position ()
gint64 | pt_player_get_duration ()
gchar * | pt_player_get_uri ()
gchar * | pt_player_get_filename ()
gchar * | pt_player_get_time_string ()
gchar * | pt_player_get_current_time_string ()
gchar * | pt_player_get_duration_time_string ()
gchar * | pt_player_get_timestamp_for_time ()
gchar * | pt_player_get_timestamp ()
gint | pt_player_get_timestamp_position ()
gboolean | pt_player_string_is_timestamp ()
gboolean | pt_player_goto_timestamp ()

## Properties

int | back | Read / Write
char * | current-uri | Read
int | forward | Read / Write
gboolean | mute | Read / Write / Construct
int | pause | Read / Write
gboolean | repeat-all | Read / Write
gboolean | repeat-selection | Read / Write
double | speed | Read / Write / Construct
int | state | Read
char * | timestamp-delimiter | Read / Write / Construct
gboolean | timestamp-fixed | Read / Write / Construct
char * | timestamp-fraction-sep | Read / Write / Construct
int | timestamp-precision | Read / Write / Construct
double | volume | Read / Write / Construct

## Signals

void | asr-final | Run First
void | asr-hypothesis | Run First
void | end-of-stream | Run First
void | error | Run First
void | jumped-back | Run First
void | jumped-forward | Run First
void | play-toggled | Run First
void | seek-done | Run First

## Types and Values

enum | PtStateType
enum | PtModeType
enum | PtPrecisionType

## Object Hierarchy

        GObject
        ╰── PtPlayer

## Includes

    #include <parlatype/parlatype.h>

## Description

PtPlayer is the GStreamer backend for Parlatype. Construct it with `pt_player_new()`. Then you have to open a file with `pt_player_open_uri()`.

The internal time unit in PtPlayer are milliseconds.

## Functions

### pt_player_new ()

    PtPlayer *
    pt_player_new (void);

Returns a new PtPlayer in PT_MODE_PLAYBACK. The next step would be to open a file with `pt_player_open_uri()`.

After use `g_object_unref()` it.

#### Returns

a new pt_player.

[transfer full]

Since: 1.6

### pt_player_set_mode ()

    void
    pt_player_set_mode (PtPlayer *self,
                        PtModeType type);

Set output mode. Initially PtPlayer is in PT_MODE_PLAYBACK. Before switching to PT_MODE_ASR the programmer has to call `pt_player_configure_asr()` and check the result. Setting the mode is an asynchronous operation and when done in paused state, it will happen only during the change to playing state.

Currently this works only well when done in paused state, in playing state there are severe synchronisation issues.

To get the results in ASR mode, connect to the “asr-hypothesis” and/or “asr-final” signal. Start recognition with `pt_player_play()`.

#### Parameters

self | a PtPlayer |
type | the desired output mode |

Since: 3.0

### pt_player_get_mode ()

    PtModeType
    pt_player_get_mode (PtPlayer *self);

Get current output mode.

#### Parameters

self | a PtPlayer |

#### Returns

the current mode

Since: 3.0

### pt_player_configure_asr ()

    gboolean
    pt_player_configure_asr (PtPlayer *self,
                             PtConfig *config,
                             GError **error);

Configure ASR setup with a PtConfig instance. This is necessary before switching into PT_MODE_ASR the first time. The configuration remains if you switch to normal playback and back to ASR again. Subsequently it can be changed in both modes.

#### Parameters

self | a PtPlayer |
config | a PtConfig |
error | return location for an error, or NULL. | [nullable]

#### Returns

TRUE on success, otherwise FALSE

Since: 3.0

### pt_player_config_is_loadable ()

    gboolean
    pt_player_config_is_loadable (PtPlayer *self,
                                  PtConfig *config);

Checks if PtPlayer is able to load the GStreamer plugin used by `config` without actually loading it. It does not guarantee that the plugin is functional, merely that it is either a private plugin of PtPlayer itself or an installed external plugin.

#### Parameters

self | a PtPlayer |
config | a PtConfig |

#### Returns

TRUE on success, otherwise FALSE

Since: 3.0

### pt_player_open_uri ()

    gboolean
    pt_player_open_uri (PtPlayer *self,
                        gchar *uri);

Opens a local audio file for playback. It doesn’t work with videos or streams. Only one file can be open at a time, playlists are not supported by the backend. Opening a new file will close the previous one.

When closing a file or on object destruction PtPlayer tries to write the last position into the file’s metadata. On opening a file it reads the metadata and jumps to the last known position if found.

The player is set to the paused state and ready for playback. To start playback use ``pt_player_play()`` .

This operation blocks until it is finished. It returns TRUE on success or FALSE on error. Errors are emitted async via “error” signal.

#### Parameters

self | a PtPlayer |
uri | the URI of the file |

#### Returns

TRUE if successful, otherwise FALSE

Since: 2.0

### pt_player_play ()

    void
    pt_player_play (PtPlayer *self);

Starts playback in playback mode at the defined speed until it reaches the end of stream (or the end of the selection). If the current position is at the end, playback will start from the beginning of the stream or selection.

In ASR mode it starts decoding the stream silently at the fastest possible speed and emitting textual results via the “asr-hypothesis” and “asr-final” signals.

#### Parameters

self | a PtPlayer |

Since: 1.4

### pt_player_play_pause ()

    void
    pt_player_play_pause (PtPlayer *self);

Toggles between playback and pause, rewinds on pause.

#### Parameters

self | a PtPlayer |

Since: 1.6

### pt_player_pause ()

    void
    pt_player_pause (PtPlayer *self);

Sets the player to the paused state, meaning it stops playback and doesn’t change position. To resume playback use ``pt_player_play()`` .

#### Parameters

self | a PtPlayer |

Since: 1.4

### pt_player_pause_and_rewind ()

    void
    pt_player_pause_and_rewind (PtPlayer *self);

Like ``pt_player_pause()`` , additionally rewinds the value of “pause” in milliseconds.

#### Parameters

self | a PtPlayer |

Since: 1.6

### pt_player_get_pause ()

    gint
    pt_player_get_pause (PtPlayer *self);

Returns the value of “pause”.

#### Parameters

self | a PtPlayer |

#### Returns

time to rewind on pause in milliseconds

Since: 1.6

### pt_player_get_media_info ()

    PtMediaInfo *
    pt_player_get_media_info (PtPlayer *self);

Get the player’s PtMediaInfo object to query the current track’s metadata.

#### Parameters

self | a PtPlayer |

#### Returns

the player’s PtMediaInfo object.

[transfer none]

Since: 4.3

### pt_player_connect_waveviewer ()

    void
    pt_player_connect_waveviewer (PtPlayer *self,
                                  PtWaveviewer *wv);

Connect a PtWaveviewer. The PtPlayer will monitor selections made in the PtWaveviewer and act accordingly.

#### Parameters

self | a PtPlayer |
wv | a PtWaveviewer |

Since: 1.6

### pt_player_set_selection ()

    void
    pt_player_set_selection (PtPlayer *self,
                             gint64 start,
                             gint64 end);

Set a selection. If the current position is outside the selection, it will be set to the selection’s start position, otherwise the current position is not changed. Playing will end at the stop position and it’s not possible to jump out of the selection until it is cleared with pt_player_clear_selection.

#### Parameters

self | a PtPlayer |
start | selection start time in milliseconds |
end | selection end time in milliseconds |

Since: 1.5

### pt_player_clear_selection ()

    void
    pt_player_clear_selection (PtPlayer *self);

Clear and reset any selection.

#### Parameters

self | a PtPlayer |

Since: 1.5

### pt_player_has_selection ()

    gboolean
    pt_player_has_selection (PtPlayer *self);

Returns whether there is currently a selection set or not.

#### Parameters

self | a PtPlayer |

#### Returns

TRUE if there is a selection

Since: 4.0

### pt_player_jump_relative ()

    void
    pt_player_jump_relative (PtPlayer *self,
                             gint milliseconds);

Skips `milliseconds` in stream. A positive value means jumping ahead. If the resulting position would be beyond the end of stream (or selection), it goes to the end of stream (or selection). A negative value means jumping back. If the resulting position would be negative (or before the selection), it jumps to position 0:00 (or to the start of the selection).

#### Parameters

self | a PtPlayer |
milliseconds | time in milliseconds to jump |

Since: 1.4

### pt_player_jump_back ()

    void
    pt_player_jump_back (PtPlayer *self);

Jumps back the value of “back”.

#### Parameters

self | a PtPlayer |

Since: 1.6

### pt_player_jump_forward ()

    void
    pt_player_jump_forward (PtPlayer *self);

Jumps forward the value of “forward”.

#### Parameters

self | a PtPlayer |

Since: 1.6

### pt_player_get_back ()

    gint
    pt_player_get_back (PtPlayer *self);

Returns the value of “back”.

#### Parameters

self | a PtPlayer |

#### Returns

time to jump back in milliseconds

Since: 1.6

### pt_player_get_forward ()

    gint
    pt_player_get_forward (PtPlayer *self);

Returns the value of “forward”.

#### Parameters

self | a PtPlayer |

#### Returns

time to jump forward in milliseconds

Since: 1.6

### pt_player_jump_to_position ()

    void
    pt_player_jump_to_position (PtPlayer *self,
                                gint milliseconds);

Jumps to a given position in stream. The position is given in `milliseconds` starting from position 0:00. A position beyond the duration of stream (or outside the selection) is ignored.

#### Parameters

self | a PtPlayer |
milliseconds | position in milliseconds |

Since: 1.4

### pt_player_get_speed ()

    gdouble
    pt_player_get_speed (PtPlayer *self);

Returns current playback speed.

#### Parameters

self | a PtPlayer |

#### Returns

playback speed

Since: 3.1

### pt_player_set_speed ()

    void
    pt_player_set_speed (PtPlayer *self,
                         gdouble speed);

Sets the speed of playback in the paused state as well as during playback. Normal speed is 1.0, everything above that is faster, everything below slower. A speed of 0 is not allowed, use `pt_player_pause()` instead. Recommended speed is starting from 0.5 as quality is rather poor below that. Parlatype doesn’t change the pitch during slower or faster playback.

#### Parameters

self | a PtPlayer |
speed | speed |

Since: 1.4

### pt_player_get_volume ()

    gdouble
    pt_player_get_volume (PtPlayer *self);

Gets the volume on a scale between 0 and 1.

#### Parameters

self | a PtPlayer |

#### Returns

the current volume

Since: 2.1

### pt_player_set_volume ()

    void
    pt_player_set_volume (PtPlayer *self,
                          gdouble volume);

Sets the volume on a scale between 0 and 1. Instead of using this method you could set the "volume" property.

#### Parameters

self | a PtPlayer |
volume | volume |

Since: 1.4

### pt_player_get_mute ()

    gboolean
    pt_player_get_mute (PtPlayer *self);

Get mute state of the audio stream.

#### Parameters

self | a PtPlayer |

#### Returns

TRUE for muted state, FALSE for normal state

Since: 2.1

### pt_player_set_mute ()

    void
    pt_player_set_mute (PtPlayer *self,
                        gboolean mute);

Mute the player (with TRUE) or set it back to normal volume (with FALSE). This remembers the volume level, so you don’t have to keep track of the old value.

#### Parameters

self | a PtPlayer |
mute | a gboolean |

Since: 2.1

### pt_player_get_position ()

    gint64
    pt_player_get_position (PtPlayer *self);

Returns the current position in stream.

#### Parameters

self | a PtPlayer |

#### Returns

position in milliseconds or -1 on failure

Since: 1.5

### pt_player_get_duration ()

    gint64
    pt_player_get_duration (PtPlayer *self);

Returns the duration of stream.

#### Parameters

self | a PtPlayer |

#### Returns

duration in milliseconds

Since: 1.5

### pt_player_get_uri ()

    gchar *
    pt_player_get_uri (PtPlayer *self);

Returns the URI of the currently open file or NULL if it can’t be determined.

#### Parameters

self | a PtPlayer |

#### Returns

the uri.

[transfer full]

Since: 1.4

### pt_player_get_filename ()

    gchar *
    pt_player_get_filename (PtPlayer *self);

Returns the display name of the currently open file or NULL if it can’t be determined.

#### Parameters

self | a PtPlayer |

#### Returns

the file name.

[transfer full]

Since: 1.4

### pt_player_get_time_string ()

    gchar *
    pt_player_get_time_string (gint time,
                               gint duration,
                               PtPrecisionType precision);

Returns the given time as a string for display to the user. Format type is determined by `duration` , e.g. if duration is long format, it returns a string in long format, too.

#### Parameters

time | time in milliseconds to converse |
duration | duration of stream in milliseconds (max time) |
precision | a PtPrecisionType |

#### Returns

the time string.

[transfer full]

Since: 1.4

### pt_player_get_current_time_string ()

    gchar *
    pt_player_get_current_time_string (PtPlayer *self,
                                       PtPrecisionType precision);

Returns the current position of the stream as a string for display to the user.

If the current position can not be determined, NULL is returned.

#### Parameters

self | a PtPlayer |
precision | a PtPrecisionType |

#### Returns

the time string.

[transfer full]

Since: 1.4

### pt_player_get_duration_time_string ()

    gchar *
    pt_player_get_duration_time_string (PtPlayer *self,
                                        PtPrecisionType precision);

Returns the duration of the stream as a string for display to the user.

If the duration can not be determined, NULL is returned.

#### Parameters

self | a PtPlayer |
precision | a PtPrecisionType |

#### Returns

the time string.

[transfer full]

Since: 1.4

### pt_player_get_timestamp_for_time ()

    gchar *
    pt_player_get_timestamp_for_time (PtPlayer *self,
                                      gint time,
                                      gint duration);

Returns the timestamp for the given time as a string. Duration is needed for some short time formats, the resulting timestamp format depends on whether duration is less than one hour or more than (including) an hour (3600000 milliseconds).

The format of the timestamp can be influenced with “timestamp-precision”, “timestamp-fixed”, “timestamp-fraction-sep” and “timestamp-delimiter”.

#### Parameters

self | a PtPlayer |
time | the time in milliseconds |
duration | duration in milliseconds |

#### Returns

the timestamp.

[transfer full]

Since: 1.6

### pt_player_get_timestamp ()

    gchar *
    pt_player_get_timestamp (PtPlayer *self);

Returns the current timestamp as a string. The format of the timestamp can be influenced with “timestamp-precision”, “timestamp-fixed”, “timestamp-fraction-sep” and “timestamp-delimiter”.

If the current position can not be determined, NULL is returned.

#### Parameters

self | a PtPlayer |

#### Returns

the timestamp.

[transfer full]

Since: 1.4

### pt_player_get_timestamp_position ()

    gint
    pt_player_get_timestamp_position (PtPlayer *self,
                                      gchar *timestamp,
                                      gboolean check_duration);

Returns the time in milliseconds represented by the timestamp or -1 for invalid timestamps.

#### Parameters

self | a PtPlayer |
timestamp | the timestamp |
check_duration | checking the timestamp’s validity also check duration |

#### Returns

the time in milliseconds represented by the timestamp or -1 for invalid timestamps

Since: 1.6

### pt_player_string_is_timestamp ()

    gboolean
    pt_player_string_is_timestamp (PtPlayer *self,
                                   gchar *timestamp,
                                   gboolean check_duration);

Returns whether the given string is a valid timestamp. With `check_duration` FALSE it checks only for the formal validity of the timestamp. With `check_duration` TRUE the timestamp must be within the duration to be valid.

See also `pt_player_goto_timestamp()` if you want to go to the timestamp’s position immediately after.

#### Parameters

self | a PtPlayer |
timestamp | the string to be checked |
check_duration | whether timestamp’s time is less or equal stream’s duration |

#### Returns

TRUE if the timestamp is valid, FALSE if not

Since: 1.4

### pt_player_goto_timestamp ()

    gboolean
    pt_player_goto_timestamp (PtPlayer *self,
                              gchar *timestamp);

Goes to the position of the timestamp. Returns false, if it’s not a valid timestamp.

#### Parameters

self | a PtPlayer |
timestamp | the timestamp to go to |

#### Returns

TRUE on success, FALSE if the timestamp is not valid

Since: 1.4

## Types and Values

### enum PtStateType

Enum values indicating PtPlayer’s current state.

#### Members

PT_STATE_STOPPED | the player is stopped |
PT_STATE_PAUSED | the player is paused |
PT_STATE_PLAYING | the player is currently playing a stream |

### enum PtModeType

Enum values indicating PtPlayer output mode.

#### Members

PT_MODE_PLAYBACK | normal audible playback |
PT_MODE_ASR | silent automatic speech recognition |

### enum PtPrecisionType

Enum values indicating desired precision of time strings.

#### Members

PT_PRECISION_SECOND | Rounds to full seconds, e.g. 1:23 (1 minute, 23 seconds) |
PT_PRECISION_SECOND_10TH | Round to 1/10 seconds, e.g. 1:23.4 |
PT_PRECISION_SECOND_100TH | Round to 1/100 seconds, e.g. 1:23.45 |

## Property Details

### The `“back”` property

      “back”                     int

Milliseconds to jump back.

Owner: PtPlayer

Flags: Read / Write

Allowed values: [1000,60000]

Default value: 10000

### The `“current-uri”` property

      “current-uri”              char *

URI of the currently loaded stream.

Owner: PtPlayer

Flags: Read

Default value: NULL

### The `“forward”` property

      “forward”                  int

Milliseconds to jump forward.

Owner: PtPlayer

Flags: Read / Write

Allowed values: [1000,60000]

Default value: 10000

### The `“mute”` property

      “mute”                     gboolean

Mute state of the audio stream.

Owner: PtPlayer

Flags: Read / Write / Construct

Default value: FALSE

### The `“pause”` property

      “pause”                    int

Milliseconds to rewind on pause.

Owner: PtPlayer

Flags: Read / Write

Allowed values: [0,10000]

Default value: 0

### The `“repeat-all”` property

      “repeat-all”               gboolean

"Play" at the end of the file replays it.

Owner: PtPlayer

Flags: Read / Write

Default value: FALSE

### The `“repeat-selection”` property

      “repeat-selection”         gboolean

"Play" at the end of a selection replays it.

Owner: PtPlayer

Flags: Read / Write

Default value: FALSE

### The `“speed”` property

      “speed”                    double

The speed for playback.

Owner: PtPlayer

Flags: Read / Write / Construct

Allowed values: [0.1,2]

Default value: 1

### The `“state”` property

      “state”                    int

The current state of PtPlayer.

Owner: PtPlayer

Flags: Read

Allowed values: [0,2]

Default value: 0

### The `“timestamp-delimiter”` property

      “timestamp-delimiter”      char *

Character to delimit start and end of timestamp. Allowed values are "None", hashtag "#", left bracket "(" and left square bracket "[". PtPlayer will of course end with a right (square) bracket if those are chosen. Any other character is changed to a hashtag "#".

Owner: PtPlayer

Flags: Read / Write / Construct

Default value: "#"

### The `“timestamp-fixed”` property

      “timestamp-fixed”          gboolean

Whether timestamp format should have a fixed number of digits.

Owner: PtPlayer

Flags: Read / Write / Construct

Default value: FALSE

### The `“timestamp-fraction-sep”` property

      “timestamp-fraction-sep”   char *

Character to separate fractions of a second from seconds. Only point "." and minus "-" are allowed. Any other character is changed to a point ".".

Owner: PtPlayer

Flags: Read / Write / Construct

Default value: "."

### The `“timestamp-precision”` property

      “timestamp-precision”      int

How precise timestamps should be.

Owner: PtPlayer

Flags: Read / Write / Construct

Allowed values: [0,3]

Default value: 1

### The `“volume”` property

      “volume”                   double

The volume for playback.

Pulseaudio sink does not propagate volume changes at GST_STATE_PAUSED or lower. This property will notify of changes only in GST_STATE_PLAYING and on state changes, e.g. from GST_STATE_READY to GST_STATE_PAUSED. Getting this property returns the real current volume level even if there was no notification before.

Owner: PtPlayer

Flags: Read / Write / Construct

Allowed values: [0,1]

Default value: 1

## Signal Details

### The `“asr-final”` signal

    void
    user_function (PtPlayer *self,
                   char     *word,
                   gpointer  user_data)

The “asr-final” signal is emitted in automatic speech recognition mode whenever a word or a sequence of words was recognized and won’t change anymore. For intermediate results see “asr-hypothesis”.

#### Parameters

self | the player emitting the signal |
word | recognized word(s) |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“asr-hypothesis”` signal

    void
    user_function (PtPlayer *self,
                   char     *word,
                   gpointer  user_data)

The “asr-hypothesis” signal is emitted in automatic speech recognition mode as an intermediate result (hypothesis) of recognized words. The hypothesis can still change. The programmer is responsible for replacing an emitted hypothesis by either the next following hypothesis or a following “asr-final” signal.

It’s not necessary to connect to this signal if you want the final result only. However, it can take a few seconds until a final result is emitted and without an intermediate hypothesis the end user might have the impression that there is nothing going on.

#### Parameters

self | the player emitting the signal |
word | probably recognized word(s) |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“end-of-stream”` signal

    void
    user_function (PtPlayer *self,
                   gpointer  user_data)

The “end-of-stream” signal is emitted when the stream is at its end or when the end of selection is reached.

#### Parameters

self | the player emitting the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“error”` signal

    void
    user_function (PtPlayer *self,
                   GError   *error,
                   gpointer  user_data)

The “error” signal is emitted on errors opening the file or during playback. It’s a severe error and the player is always reset.

#### Parameters

self | the player emitting the signal |
error | a GError |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“jumped-back”` signal

    void
    user_function (PtPlayer *self,
                   gpointer  user_data)

The “jumped-back” signal is emitted when the player jumped back.

#### Parameters

self | the player emitting the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“jumped-forward”` signal

    void
    user_function (PtPlayer *self,
                   gpointer  user_data)

The “jumped-forward” signal is emitted when the player jumped forward.

#### Parameters

self | the player emitting the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“play-toggled”` signal

    void
    user_function (PtPlayer *self,
                   gpointer  user_data)

The “play-toggled” signal is emitted when the player changed to pause or play.

#### Parameters

self | the player emitting the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“seek-done”` signal

    void
    user_function (PtPlayer *self,
                   gpointer  user_data)

The “seek-done” signal is emitted when a seek has finished successfully. If several seeks are queued up, only the last one emits a signal.

#### Parameters

self | the player emitting the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First