## BtSong

BtSong — class of a song project object (contains BtSongInfo, BtSetup, BtSequence and BtWavetable)

## Synopsis

    #include <libbtcore/core.h>

                        BtSong;
                        BtSongClass;
    BtSong *            bt_song_new                         (const BtApplication * const app);
    void                bt_song_set_unsaved                 (const BtSong * const self,
                                                             const gboolean unsaved);
    gboolean            bt_song_play                        (const BtSong * const self);
    gboolean            bt_song_stop                        (const BtSong * const self);
    gboolean            bt_song_pause                       (const BtSong * const self);
    gboolean            bt_song_continue                    (const BtSong * const self);
    gboolean            bt_song_update_playback_position    (const BtSong * const self);
    void                bt_song_write_to_xml_file           (const BtSong * const self);
    void                bt_song_write_to_highlevel_dot_file (const BtSong * const self);
    void                bt_song_write_to_lowlevel_dot_file  (const BtSong * const self);

## Object Hierarchy

      GObject
       +----BtSong

## Implemented Interfaces

BtSong implements

## Properties

      "app"                      BtApplication*        : Read / Write / Construct Only
      "bin"                      GstBin*               : Read
      "is-idle"                  gboolean              : Read / Write
      "is-playing"               gboolean              : Read
      "master"                   BtSinkMachine*        : Read / Write
      "play-pos"                 gulong                : Read / Write
      "sequence"                 BtSequence*           : Read
      "setup"                    BtSetup*              : Read
      "song-info"                BtSongInfo*           : Read
      "song-io"                  BtSongIO*             : Read / Write
      "unsaved"                  gboolean              : Read / Write
      "wavetable"                BtWavetable*          : Read

## Description

A song is the top-level container object to manage all song-related objects.

To load or save a song, use a BtSongIO object. These implement loading and saving for different file-formats.

## Details

### BtSong

    typedef struct _BtSong BtSong;

Song project object (contains BtSongInfo, BtSetup and BtSequence)

### BtSongClass

    typedef struct {
      const GObjectClass parent;
    } BtSongClass;

Base class for songs

const GObjectClass `parent`; | parent class type

### bt_song_new ()

    BtSong *            bt_song_new                         (const BtApplication * const app);

Create a new instance. The new song instance automatically has one instance of BtSetup, BtSequence and BtSongInfo. These instances can be retrieved via the respecting properties.

For example use following code to retrive a BtSequence from the song class:

    1
    2
    3

    BtSequence *sequence;
    ...
    g_object_get(BT_SONG(song), "sequence", &sequence, NULL);

`app` : | the application object the songs belongs to.
Returns : | the new instance or `NULL` in case of an error

### bt_song_set_unsaved ()

    void                bt_song_set_unsaved                 (const BtSong * const self,
                                                             const gboolean unsaved);

Use this method instead of directly setting the state via `g_object_set()` to avoid double notifies, if the state is unchanged.

`self` : | the song that should be changed
`unsaved` : | the new state of the songs unsaved flag

### bt_song_play ()

    gboolean            bt_song_play                        (const BtSong * const self);

Starts to play the specified song instance from beginning. This methods emits the "play" signal.

`self` : | the song that should be played
Returns : | `TRUE` for success

### bt_song_stop ()

    gboolean            bt_song_stop                        (const BtSong * const self);

Stops the playback of the specified song instance.

`self` : | the song that should be stopped
Returns : | `TRUE` for success

### bt_song_pause ()

    gboolean            bt_song_pause                       (const BtSong * const self);

Pauses the playback of the specified song instance.

`self` : | the song that should be paused
Returns : | `TRUE` for success

### bt_song_continue ()

    gboolean            bt_song_continue                    (const BtSong * const self);

Continues the playback of the specified song instance.

`self` : | the song that should be paused
Returns : | `TRUE` for success

### bt_song_update_playback_position ()

    gboolean            bt_song_update_playback_position    (const BtSong * const self);

Updates the playback-position counter to fire all notify::playback-pos handlers.

`self` : | the song that should update its playback-pos counter
Returns : | `FALSE` if the song is not playing

### bt_song_write_to_xml_file ()

    void                bt_song_write_to_xml_file           (const BtSong * const self);

To aid debugging applications one can use this method to write out the whole network of gstreamer elements that form the song into an XML file. The file will be written to '/tmp' and will be named according the 'name' property of the BtSongInfo. This XML file can be loaded into gst-editor.

`self` : | the song that should be written

### bt_song_write_to_highlevel_dot_file ()

    void                bt_song_write_to_highlevel_dot_file (const BtSong * const self);

To aid debugging applications one can use this method to write out the whole network of gstreamer elements from the songs perspective into an dot file. The file will be written to '/tmp' and will be named according the 'name' property of the BtSongInfo. This file can be processed with graphviz to get an image.

    1

    dot -Tpng -oimage.png graph_highlevel.dot

`self` : | the song that should be written

### bt_song_write_to_lowlevel_dot_file ()

    void                bt_song_write_to_lowlevel_dot_file  (const BtSong * const self);

To aid debugging applications one can use this method to write out the whole network of gstreamer elements that form the song into an dot file. The file will be written to '/tmp' and will be named according the 'name' property of the BtSongInfo. This file can be processed with graphviz to get an image.

    1

    dot -Tpng -oimage.png graph_lowlevel.dot

`self` : | the song that should be written

## Property Details

### The `"app"` property

      "app"                      BtApplication*        : Read / Write / Construct Only

set application object, the song belongs to.

### The `"bin"` property

      "bin"                      GstBin*               : Read

songs top-level GstElement container.

### The `"is-idle"` property

      "is-idle"                  gboolean              : Read / Write

request that the song should idle-loop if not playing.

Default value: FALSE

### The `"is-playing"` property

      "is-playing"               gboolean              : Read

tell wheter the song is playing right now or not.

Default value: FALSE

### The `"master"` property

      "master"                   BtSinkMachine*        : Read / Write

songs audio_sink.

### The `"play-pos"` property

      "play-pos"                 gulong                : Read / Write

position of the play cursor of the sequence in timeline bars.

Allowed values: <= G_MAXLONG

### The `"sequence"` property

      "sequence"                 BtSequence*           : Read

songs sequence sub object.

### The `"setup"` property

      "setup"                    BtSetup*              : Read

songs setup sub object.

### The `"song-info"` property

      "song-info"                BtSongInfo*           : Read

songs metadata sub object.

### The `"song-io"` property

      "song-io"                  BtSongIO*             : Read / Write

the song-io plugin during i/o operations.

### The `"unsaved"` property

      "unsaved"                  gboolean              : Read / Write

tell wheter the current state of the song has been saved.

Default value: TRUE

### The `"wavetable"` property

      "wavetable"                BtWavetable*          : Read

songs wavetable sub object.