PtPlayer: Parlatype Reference Manual

## PtPlayer PtPlayer — The GStreamer backend for Parlatype. |

## Stability Level

Unstable, unless otherwise indicated

## Functions

PtPlayer * | pt_player_new ()
void | pt_player_open_uri_async ()
gboolean | pt_player_open_uri_finish ()
gboolean | pt_player_open_uri ()
void | pt_player_cancel ()
void | pt_player_play ()
void | pt_player_pause ()
void | pt_player_set_selection ()
void | pt_player_clear_selection ()
void | pt_player_jump_relative ()
void | pt_player_jump_to_position ()
void | pt_player_jump_to_permille ()
gint | pt_player_get_permille ()
void | pt_player_set_speed ()
void | pt_player_set_volume ()
void | pt_player_mute_volume ()
void | pt_player_rewind ()
void | pt_player_fast_forward ()
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 ()
gboolean | pt_player_string_is_timestamp ()
gboolean | pt_player_goto_timestamp ()
PtWavedata * | pt_player_get_data ()

## Properties

gdouble | speed | Read / Write / Construct
gdouble | volume | Read / Write / Construct

## Signals

void | end-of-stream | Run First
void | error | Run First
void | load-progress | Run First

## Types and Values

struct | PtPlayer
enum | PtPrecisionType

## Object Hierarchy

        GObject
        ╰── PtPlayer

## Implemented Interfaces

PtPlayer implements GInitable.

## Includes

    #include <parlatype/pt-player.h>

## Description

PtPlayer is the GStreamer backend for Parlatype. Construct it with `pt_player_new()`. Then you have to open a file, either with `pt_player_open_uri_async()` or `pt_player_open_uri()`, the blocking version.

The internal time unit in PtPlayer are milliseconds and for scale widgets there is a scale from 0 to 1000. Use it to jump to a position or to update your widget.

While playing PtPlayer emits these signals:

- end-of-stream: End of file reached, in the GUI you might want to jump to the beginning, reset play button etc.

- error: A fatal error occured, the player is reset. There's an error message.

PtPlayer has two properties:

- speed: is a double from 0.5 to 1.5. 1.0 is normal playback, < 1.0 is slower, > 1.0 is faster. Changing the "speed" property doesn't change playback though. Use the method instead.

- Volume is a double from 0 to 1. It can be set via the method or setting the "volume" property.

## Functions

### pt_player_new ()

    PtPlayer *
    pt_player_new (GError **error);

This is a failable constructor. It fails, if GStreamer doesn't init or a plugin is missing. In this case NULL is returned, error is set.

After use `g_object_unref()` it.

#### Parameters

error | return location for an error, or NULL. | [allow-none]

#### Returns

a new pt_player.

[transfer full]

### pt_player_open_uri_async ()

    void
    pt_player_open_uri_async (PtPlayer *player,
                              gchar *uri,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

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 is an asynchronous operation, to get the result call `pt_player_open_uri_finish()` in your callback. For the blocking version see `pt_player_open_uri()`.

While loading the file there is a “load-progress” signal emitted which stops before reaching 100%. Don't use it to determine whether the operation is finished.

#### Parameters

player | a PtPlayer |
uri | the URI of the file |
callback | a GAsyncReadyCallback to call when the operation is complete. | [scope async]
user_data | user_data for callback. | [closure]

### pt_player_open_uri_finish ()

    gboolean
    pt_player_open_uri_finish (PtPlayer *player,
                               GAsyncResult *result,
                               GError **error);

Gives the result of the async opening operation. A cancelled operation results in an error, too.

#### Parameters

player | a PtPlayer |
result | the GAsyncResult passed to your GAsyncReadyCallback |
error | a pointer to a NULL GError, or NULL. | [allow-none]

#### Returns

TRUE if successful, or FALSE with error set

### pt_player_open_uri ()

    gboolean
    pt_player_open_uri (PtPlayer *player,
                        gchar *uri,
                        GError **error);

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 and an error. For the asynchronous version see `pt_player_open_uri_async()`.

While loading the file there is a “load-progress” signal emitted. However, it doesn't emit 100%, the operation is finished when TRUE is returned.

#### Parameters

player | a PtPlayer |
uri | the URI of the file |
error | return location for an error, or NULL. | [allow-none]

#### Returns

TRUE if successful, or FALSE with error set

### pt_player_cancel ()

    void
    pt_player_cancel (PtPlayer *player);

Cancels the file opening operation, which triggers an error message.

#### Parameters

player | a PtPlayer |

### 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)..

#### Parameters

player | a PtPlayer |

### 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()`` .

#### Parameters

player | a PtPlayer |

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

#### Parameters

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

### pt_player_clear_selection ()

    void
    pt_player_clear_selection (PtPlayer *player);

Clear and reset any selection.

#### Parameters

player | a PtPlayer |

### 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).

#### Parameters

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

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

#### Parameters

player | a PtPlayer |
milliseconds | position in milliseconds |

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

#### Parameters

player | a PtPlayer |
permille | scale position between 0 and 1000 |

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

#### Parameters

player | a PtPlayer |

#### Returns

a scale position between 0 and 1000 or -1 on failure

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

Note: If you want to change the speed during playback, you have to use this method. Changing the "speed" property of PtPlayer, will take effect only later.

#### Parameters

player | a PtPlayer |
speed | speed |

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

#### Parameters

player | a PtPlayer |
volume | volume |

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

#### Parameters

player | a PtPlayer |
mute | a gboolean |

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

This is only available with GStreamer >= 1.6.3 (because of https://bugzilla.gnome.org/show_bug.cgi?id=757033).

If you call this with an older version of GStreamer, it will only print a warning to standard output.

Note that depending on the file/stream format this works more or less good.

#### Parameters

player | a PtPlayer |
speed | the speed |

### pt_player_fast_forward ()

    void
    pt_player_fast_forward (PtPlayer *player,
                            gdouble speed);

Play fast forward at the given speed.

This is only available with GStreamer >= 1.6.3 (because rewind is working properly with that version).

If you call this with an older version of GStreamer, it will only print a warning to standard output.

#### Parameters

player | a PtPlayer |
speed | the speed |

### pt_player_get_position ()

    gint64
    pt_player_get_position (PtPlayer *player);

Returns the current position in stream.

#### Parameters

player | a PtPlayer |

#### Returns

position in milliseconds or -1 on failure

### pt_player_get_duration ()

    gint64
    pt_player_get_duration (PtPlayer *player);

Returns the duration of stream.

#### Parameters

player | a PtPlayer |

#### Returns

duration in milliseconds

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

#### Parameters

player | a PtPlayer |

#### Returns

the uri.

[transfer full]

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

#### Parameters

player | a PtPlayer |

#### Returns

the file name.

[transfer full]

### 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]

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

#### Parameters

player | a PtPlayer |
precision | a PtPrecisionType |

#### Returns

the time string.

[transfer full]

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

#### Parameters

player | a PtPlayer |
precision | a PtPrecisionType |

#### Returns

the time string.

[transfer full]

### pt_player_get_timestamp ()

    gchar *
    pt_player_get_timestamp (PtPlayer *player);

Returns the current timestamp as a string. The format of timestamps can not be changed.

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

#### Parameters

player | a PtPlayer |

#### Returns

the timestamp.

[transfer full]

### pt_player_string_is_timestamp ()

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

Returns whether the given string is a valid timestamp.

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

#### Parameters

player | a PtPlayer |
timestamp | the string to be checked |

#### Returns

TRUE if the timestamp is valid, FALSE if not

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

#### Parameters

player | a PtPlayer |
timestamp | the timestamp to go to |

#### Returns

TRUE on success, FALSE if the timestamp is not valid

### pt_player_get_data ()

    PtWavedata *
    pt_player_get_data (PtPlayer *player,
                        gint pps);

Returns wave data needed for visual representation as raw data. The requested resolution is given as pixel per seconds, e.g. 100 means one second is represented by 100 samples, is 100 pixels wide. The returned resolution doesn't have to be necessarily exactly the requested resolution, it might be a bit differnt, depending on the bit rate.

#### Parameters

player | a PtPlayer |
pps | the requested pixel per second ratio |

#### Returns

the PtWavedata.

[transfer full]

## Types and Values

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

#### 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 `“speed”` property

      “speed”                    gdouble

The speed for playback.

Flags: Read / Write / Construct

Allowed values: [0.1,2]

Default value: 1

### The `“volume”` property

      “volume”                   gdouble

The volume for playback.

Flags: Read / Write / Construct

Allowed values: [0,1]

Default value: 1

## Signal Details

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

#### Parameters

player | 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 *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.

#### Parameters

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

Flags: Run First

### The `“load-progress”` signal

    void
    user_function (PtPlayer *player,
                   gdouble   progress,
                   gpointer  user_data)

Indicates progress on a scale from 0.0 to 1.0, however it does not emit the value 0.0 nor 1.0. Wait for a TRUE player-state-changed signal or an error signal to dismiss a gui element showing progress.

#### Parameters

player | the player emitting the signal |
progress | the new progress state, ranging from 0.0 to 1.0 |
user_data | user data set when the signal handler was connected. |

Flags: Run First