BtSongInfo: Buzztrax Bt-Core Reference Manual

## BtSongInfo BtSongInfo — class that keeps the meta-data for a BtSong instance |

## Functions

BtSongInfo * | bt_song_info_new ()
const gchar * | bt_song_info_get_change_dts_in_local_tz ()
gint | bt_song_info_get_seconds_since_last_saved ()
GstClockTime | bt_song_info_tick_to_time ()
gulong | bt_song_info_time_to_tick ()
void | bt_song_info_time_to_m_s_ms ()
void | bt_song_info_tick_to_m_s_ms ()

## Properties

gchar * | author | Read / Write
gulong | bars | Read / Write
gulong | bpm | Read / Write
gchar * | change-dts | Read / Write
gchar * | create-dts | Read / Write
gchar * | file-name | Read / Write
gchar * | genre | Read / Write
gchar * | info | Read / Write
gchar * | name | Read / Write
BtSong * | song | Read / Write / Construct Only
gpointer | taglist | Read
guint64 | tick-duration | Read
gulong | tpb | Read / Write

## Types and Values

struct | BtSongInfo

## Object Hierarchy

        GObject
        ╰── BtSongInfo

## Implemented Interfaces

BtSongInfo implements BtPersistence.

## Includes

    #include <libbtcore/core.h>

## Description

This class exposes the meta-data of a song as GObject properties. These are for one pure data fields such as author and song name. These fields get used when recording a song to a file (rendering) in the form of meta-tags.

Further there are fields that determine rythm and song-speed. The speed is determined by “bpm”. The rythm is determined by “bars” and “tpb”. If 'bars' is 16, than on can have 1/16 notes. And if 'ticks per beat' is 4 one will have 4 beats - a classic 4/4 meassure. For a 3/4 meassure, 'bars' would be 12. Thus bars = beats * tpb.

Finally, the class offers a couple of timing related conversion functions.

## Functions

### bt_song_info_new ()

    BtSongInfo *
    bt_song_info_new (const BtSong * const song);

Create a new instance

#### Parameters

song | the song the new instance belongs to |

#### Returns

the new instance or `NULL` in case of an error

### bt_song_info_get_change_dts_in_local_tz ()

    const gchar *
    bt_song_info_get_change_dts_in_local_tz
                                   (const BtSongInfo * const self);

Convert the BtSongInfo::change-dts to local time zone.

Return: the time stamp in iso 8601 format

#### Parameters

self | the song_info |

### bt_song_info_get_seconds_since_last_saved ()

    gint
    bt_song_info_get_seconds_since_last_saved
                                   (const BtSongInfo * const self);

Calculate the seconds since last save time or the creation time if the song is new.

Return: the seconds

#### Parameters

self | the song_info |

### bt_song_info_tick_to_time ()

    GstClockTime
    bt_song_info_tick_to_time (const BtSongInfo * const self,
                               const gulong tick);

Convert a given tick position to the time in µs.

#### Parameters

self | the song_info |
tick | the tick position |

#### Returns

the time in µs

### bt_song_info_time_to_tick ()

    gulong
    bt_song_info_time_to_tick (const BtSongInfo * const self,
                               const GstClockTime ts);

Convert a given time in µs to the tick position.

#### Parameters

self | the song_info |
ts | the time in µs |

#### Returns

the integer tick position

### bt_song_info_time_to_m_s_ms ()

    void
    bt_song_info_time_to_m_s_ms (const BtSongInfo * const self,
                                 gulong ts,
                                 gulong *m,
                                 gulong *s,
                                 gulong *ms);

Convert a given time in µs to minutes, seconds and milliseconds.

#### Parameters

self | the song_info |
ts | the time in µs |
m | location for the minutes |
s | location for the seconds |
ms | location for the milliseconds |

### bt_song_info_tick_to_m_s_ms ()

    void
    bt_song_info_tick_to_m_s_ms (const BtSongInfo * const self,
                                 const gulong tick,
                                 gulong *m,
                                 gulong *s,
                                 gulong *ms);

Convert a given tick position to minutes, seconds and milliseconds.

#### Parameters

self | the song_info |
tick | the tick position |
m | location for the minutes |
s | location for the seconds |
ms | location for the milliseconds |

## Types and Values

### struct BtSongInfo

    struct BtSongInfo;

holds song metadata

## Property Details

### The `“author”` property

      “author”                   gchar *

songs author.

Flags: Read / Write

Default value: NULL

### The `“bars”` property

      “bars”                     gulong

how many bars per meassure.

Flags: Read / Write

Allowed values: [1,64]

### The `“bpm”` property

      “bpm”                      gulong

how many beats should be played in a minute.

Flags: Read / Write

Allowed values: [1,1000]

### The `“change-dts”` property

      “change-dts”               gchar *

song changed date time stamp (iso 8601 format).

Flags: Read / Write

Default value: NULL

### The `“create-dts”` property

      “create-dts”               gchar *

song creation date time stamp (iso 8601 format).

Flags: Read / Write

Default value: NULL

### The `“file-name”` property

      “file-name”                gchar *

songs file name.

Flags: Read / Write

Default value: NULL

### The `“genre”` property

      “genre”                    gchar *

songs genre.

Flags: Read / Write

Default value: NULL

### The `“info”` property

      “info”                     gchar *

songs freeform info.

Flags: Read / Write

Default value: "comment me!"

### The `“name”` property

      “name”                     gchar *

songs name.

Flags: Read / Write

Default value: "untitled song"

### The `“song”` property

      “song”                     BtSong *

song object, the song-info belongs to.

Flags: Read / Write / Construct Only

### The `“taglist”` property

      “taglist”                  gpointer

songs meta data as a taglist.

Flags: Read

### The `“tick-duration”` property

      “tick-duration”            guint64

the duration for a tick in µs calculated form the song tempo.

Flags: Read

Allowed values: >= 1

Default value: 1

### The `“tpb”` property

      “tpb”                      gulong

event granularity in one beat.

Flags: Read / Write

Allowed values: [1,128]