pt_player_new ()

PtPlayer *
pt_player_new (void);

Returns a new PtPlayer. You have to set it up for playback with pt_player_setup_player() before doing anything else.

After use g_object_unref() it.

Since: 1.6

pt_player_setup_player ()

gboolean
pt_player_setup_player (PtPlayer *player,
                        GError **error);

Setup the GStreamer pipeline for playback. This or pt_player_setup_sphinx() must be called first on a new PtPlayer object. It’s a programmer’s error to do anything with the PtPlayer before calling the setup function.

Since: 1.6

pt_player_setup_sphinx ()

gboolean
pt_player_setup_sphinx (PtPlayer *player,
                        GError **error);

Setup the GStreamer pipeline for automatic speech recognition using CMU sphinx. This loads resources like language model and dictionary and might take a few seconds. There is no audio output in this mode. Connect to the “asr-hypothesis” and/or “asr-final” signal to get the results. Start recognition with pt_player_play().

Since: 1.6

pt_player_open_uri ()

gboolean
pt_player_open_uri (PtPlayer *player,
                    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.

Since: 2.0

pt_player_play ()

void
pt_player_play (PtPlayer *player);

Starts playback 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 stream or selection.

Since: 1.4

pt_player_play_pause ()

void
pt_player_play_pause (PtPlayer *player);

Toggles between playback and pause, rewinds on pause.

Since: 1.6

pt_player_pause ()

void
pt_player_pause (PtPlayer *player);

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

Since: 1.4

pt_player_pause_and_rewind ()

void
pt_player_pause_and_rewind (PtPlayer *player);

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

Since: 1.6

pt_player_get_pause ()

gint
pt_player_get_pause (PtPlayer *player);

Returns the value of “pause”.

Since: 1.6

pt_player_connect_waveviewer ()

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

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

Since: 1.6

pt_player_set_selection ()

void
pt_player_set_selection (PtPlayer *player,
                         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.

Since: 1.5

pt_player_clear_selection ()

void
pt_player_clear_selection (PtPlayer *player);

Clear and reset any selection.

Since: 1.5

pt_player_selection_active ()

gboolean
pt_player_selection_active (PtPlayer *player);

Returns whether there is currently a selection set or not.

Since: 1.6

pt_player_jump_relative ()

void
pt_player_jump_relative (PtPlayer *player,
                         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).

Since: 1.4

pt_player_jump_back ()

void
pt_player_jump_back (PtPlayer *player);

Jumps back the value of “back”.

Since: 1.6

pt_player_jump_forward ()

void
pt_player_jump_forward (PtPlayer *player);

Jumps forward the value of “forward”.

Since: 1.6

pt_player_get_back ()

gint
pt_player_get_back (PtPlayer *player);

Returns the value of “back”.

Since: 1.6

pt_player_get_forward ()

gint
pt_player_get_forward (PtPlayer *player);

Returns the value of “forward”.

Since: 1.6

pt_player_jump_to_position ()

void
pt_player_jump_to_position (PtPlayer *player,
                            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.

Since: 1.4

pt_player_jump_to_permille ()

void
pt_player_jump_to_permille (PtPlayer *player,
                            guint permille);

This is used for scale widgets. Start of stream is at 0, end of stream is at 1000. This will jump to the given position. If your widget uses a different scale, it’s up to you to convert it to 1/1000. Values beyond 1000 are not allowed, values outside the selection are ignored.

Since: 1.4

pt_player_get_permille ()

gint
pt_player_get_permille (PtPlayer *player);

This is used for scale widgets. If the scale has to synchronize with the current position in stream, this gives the position on a scale between 0 and 1000.

Failure in querying the position returns -1.

Since: 1.4

pt_player_set_speed ()

void
pt_player_set_speed (PtPlayer *player,
                     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.

Since: 1.4

pt_player_get_volume ()

gdouble
pt_player_get_volume (PtPlayer *player);

Gets the volume on a scale between 0 and 1.

Since: 2.1

pt_player_set_volume ()

void
pt_player_set_volume (PtPlayer *player,
                      gdouble volume);

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

Since: 1.4

pt_player_get_mute ()

gboolean
pt_player_get_mute (PtPlayer *player);

Get mute state of the audio stream.

Since: 2.1

pt_player_set_mute ()

void
pt_player_set_mute (PtPlayer *player,
                    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.

Since: 2.1

pt_player_mute_volume ()

void
pt_player_mute_volume (PtPlayer *player,
                       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.

Since: 1.4

pt_player_rewind ()

void
pt_player_rewind (PtPlayer *player,
                  gdouble speed);

Rewinds at the given speed. speed accepts positive as well as negative values and normalizes them to play backwards.

Since: 1.5

pt_player_fast_forward ()

void
pt_player_fast_forward (PtPlayer *player,
                        gdouble speed);

Play fast forward at the given speed.

Since: 1.5

pt_player_get_position ()

gint64
pt_player_get_position (PtPlayer *player);

Returns the current position in stream.

Since: 1.5

pt_player_get_duration ()

gint64
pt_player_get_duration (PtPlayer *player);

Returns the duration of stream.

Since: 1.5

pt_player_get_uri ()

gchar *
pt_player_get_uri (PtPlayer *player);

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

Since: 1.4

pt_player_get_filename ()

gchar *
pt_player_get_filename (PtPlayer *player);

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

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.

Since: 1.4

pt_player_get_current_time_string ()

gchar *
pt_player_get_current_time_string (PtPlayer *player,
                                   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.

Since: 1.4

pt_player_get_duration_time_string ()

gchar *
pt_player_get_duration_time_string (PtPlayer *player,
                                    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.

Since: 1.4

pt_player_get_timestamp_for_time ()

gchar *
pt_player_get_timestamp_for_time (PtPlayer *player,
                                  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”.

Since: 1.6

pt_player_get_timestamp ()

gchar *
pt_player_get_timestamp (PtPlayer *player);

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.

Since: 1.4

pt_player_get_timestamp_position ()

gint
pt_player_get_timestamp_position (PtPlayer *player,
                                  gchar *timestamp,
                                  gboolean 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 *player,
                               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.

Since: 1.4

pt_player_goto_timestamp ()

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

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

Since: 1.4

struct PtPlayer

struct PtPlayer;

The PtPlayer contains only private fields and should not be directly accessed.

enum PtPrecisionType

Enum values indicating desired precision of time strings.

The “back” property

  “back”                     int

Milliseconds to jump back.

Owner: PtPlayer

Flags: Read / Write

Allowed values: [1000,60000]

Default value: 10000

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 “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.

Owner: PtPlayer

Flags: Read / Write / Construct

Allowed values: [0,1]

Default value: 1

The “asr-final” signal

void
user_function (PtPlayer *player,
               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.

Flags: Run First

The “asr-hypothesis” signal

void
user_function (PtPlayer *player,
               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, an emitted hypothesis replaces the former hypothesis and is finalized via the “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.

Flags: Run First

The “end-of-stream” signal

void
user_function (PtPlayer *player,
               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.

Flags: Run First

The “error” signal

void
user_function (PtPlayer *player,
               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.

Flags: Run First

The “jumped-back” signal

void
user_function (PtPlayer *player,
               gpointer  user_data)

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

Flags: Run First

The “jumped-forward” signal

void
user_function (PtPlayer *player,
               gpointer  user_data)

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

Flags: Run First

The “play-toggled” signal

void
user_function (PtPlayer *player,
               gpointer  user_data)

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

Flags: Run First