Functions

Track subsystem

Functions

bool sp_track_is_loaded (sp_track *track)
sp_error sp_track_error (sp_track *track)
sp_track_offline_status sp_track_offline_get_status (sp_track *track)
sp_track_availability sp_track_get_availability (sp_session *session, sp_track *track)
bool sp_track_is_local (sp_session *session, sp_track *track)
bool sp_track_is_autolinked (sp_session *session, sp_track *track)
sp_tracksp_track_get_playable (sp_session *session, sp_track *track)
bool sp_track_is_placeholder (sp_track *track)
bool sp_track_is_starred (sp_session *session, sp_track *track)
sp_error sp_track_set_starred (sp_session *session, sp_track *const *tracks, int num_tracks, bool star)
int sp_track_num_artists (sp_track *track)
sp_artistsp_track_artist (sp_track *track, int index)
sp_albumsp_track_album (sp_track *track)
const char * sp_track_name (sp_track *track)
int sp_track_duration (sp_track *track)
int sp_track_popularity (sp_track *track)
int sp_track_disc (sp_track *track)
int sp_track_index (sp_track *track)
sp_tracksp_localtrack_create (const char *artist, const char *title, const char *album, int length)
sp_error sp_track_add_ref (sp_track *track)
sp_error sp_track_release (sp_track *track)

Function Documentation

sp_track* sp_localtrack_create ( const char *  artist,
const char *  title,
const char *  album,
int  length 
)

Returns the newly created local track

Parameters:
[in] artist Name of the artist
[in] title Song title
[in] album Name of the album, or an empty string if not available
[in] length Length in MS, or -1 if not available.
Returns:
A track.
sp_error sp_track_add_ref ( sp_track track  ) 

Increase the reference count of a track

Parameters:
[in] track The track object
Returns:
One of the following errors, from sp_error SP_ERROR_OK
Examples:
browse.c.
sp_album* sp_track_album ( sp_track track  ) 

The album of the specified track

Parameters:
[in] track A track object
Returns:
The album of the given track. You need to increase the refcount if you want to keep the pointer around. If no metadata is available for the track yet, this function returns 0.
sp_artist* sp_track_artist ( sp_track track,
int  index 
)

The artist matching the specified index performing on the current track.

Parameters:
[in] track The track whose participating artist you are interested in
[in] index The index for the participating artist. Should be in the interval [0, sp_track_num_artists() - 1]
Returns:
The participating artist, or NULL if invalid index
Examples:
browse.c.
int sp_track_disc ( sp_track track  ) 

Returns the disc number for a track

Parameters:
[in] track A track object
Returns:
Disc index. Possible values are [1, total number of discs on album] This function returns valid data only for tracks appearing in a browse artist or browse album result (otherwise returns 0).
Examples:
browse.c.
int sp_track_duration ( sp_track track  ) 

The duration, in milliseconds, of the specified track

Parameters:
[in] track A track object
Returns:
The duration of the specified track, in milliseconds If no metadata is available for the track yet, this function returns 0.
Examples:
browse.c.
sp_error sp_track_error ( sp_track track  ) 

Return an error code associated with a track. For example if it could not load

Parameters:
[in] track The track
Returns:
One of the following errors, from sp_error SP_ERROR_OK SP_ERROR_IS_LOADING SP_ERROR_OTHER_PERMANENT
Examples:
browse.c, and jukebox.c.
sp_track_availability sp_track_get_availability ( sp_session session,
sp_track track 
)

Return availability for a track

Parameters:
[in] session Session
[in] track The track
Returns:
Availability status, see sp_track_availability
Note:
The track must be loaded or this function will always SP_TRACK_AVAILABILITY_UNAVAILABLE
See also:
sp_track_is_loaded()
sp_track* sp_track_get_playable ( sp_session session,
sp_track track 
)

Return the actual track that will be played if the given track is played

Parameters:
[in] session Session
[in] track The track
Returns:
A track
int sp_track_index ( sp_track track  ) 

Returns the position of a track on its disc

Parameters:
[in] track A track object
Returns:
Track position, starts at 1 (relative the corresponding disc) This function returns valid data only for tracks appearing in a browse artist or browse album result (otherwise returns 0).
Examples:
browse.c.
bool sp_track_is_autolinked ( sp_session session,
sp_track track 
)

Return true if the track is autolinked to another track.

Parameters:
[in] session Session
[in] track The track
Returns:
True if track is autolinked.
Note:
The track must be loaded or this function will always return false.
See also:
sp_track_is_loaded()
bool sp_track_is_loaded ( sp_track track  ) 

Return whether or not the track metadata is loaded.

Parameters:
[in] track The track
Returns:
True if track is loaded
Note:
This is equivalent to checking if sp_track_error() not returns SP_ERROR_IS_LOADING.
Examples:
browse.c.
bool sp_track_is_local ( sp_session session,
sp_track track 
)

Return true if the track is a local file.

Parameters:
[in] session Session
[in] track The track
Returns:
True if track is a local file.
Note:
The track must be loaded or this function will always return false.
See also:
sp_track_is_loaded()
bool sp_track_is_placeholder ( sp_track track  ) 

Return true if the track is a placeholder. Placeholder tracks are used to store other objects than tracks in the playlist. Currently this is used in the inbox to store artists, albums and playlists.

Use sp_link_create_from_track() to get a link object that points to the real object this "track" points to.

Parameters:
[in] track The track
Returns:
True if track is a placeholder
Note:
Contrary to most functions the track does not have to be loaded for this function to return correct value
bool sp_track_is_starred ( sp_session session,
sp_track track 
)

Return true if the track is starred by the currently logged in user.

Parameters:
[in] session Session
[in] track The track
Returns:
True if track is starred.
Note:
The track must be loaded or this function will always return false.
See also:
sp_track_is_loaded()
Examples:
browse.c.
const char* sp_track_name ( sp_track track  ) 

The string representation of the specified track's name

Parameters:
[in] track A track object
Returns:
The string representation of the specified track's name. Returned string is valid as long as the album object stays allocated and no longer than the next call to sp_session_process_events() If no metadata is available for the track yet, this function returns empty string.
Examples:
browse.c, and jukebox.c.
int sp_track_num_artists ( sp_track track  ) 

The number of artists performing on the specified track

Parameters:
[in] track The track whose number of participating artists you are interested in
Returns:
The number of artists performing on the specified track. If no metadata is available for the track yet, this function returns 0.
Examples:
browse.c.
sp_track_offline_status sp_track_offline_get_status ( sp_track track  ) 

Return offline status for a track. sp_session_callbacks::metadata_updated() will be invoked when offline status of a track changes

Parameters:
[in] track The track
Returns:
Stats as described by sp_track_offline_status
int sp_track_popularity ( sp_track track  ) 

Returns popularity for track

Parameters:
[in] track A track object
Returns:
Popularity in range 0 to 100, 0 if undefined. If no metadata is available for the track yet, this function returns 0.
Examples:
browse.c.
sp_error sp_track_release ( sp_track track  ) 

Decrease the reference count of a track

Parameters:
[in] track The track object
Returns:
One of the following errors, from sp_error SP_ERROR_OK
Examples:
browse.c.
sp_error sp_track_set_starred ( sp_session session,
sp_track *const *  tracks,
int  num_tracks,
bool  star 
)

Star/Unstar the specified track

Parameters:
[in] session Session
[in] tracks Array of pointer to tracks.
[in] num_tracks Length of tracks array
[in] star Starred status of the track
Note:
This will fail silently if playlists are disabled.
See also:
sp_set_playlists_enabled()

Generated on Wed Jun 13 2012 14:22:40.
Copyright © 2006–2012 Spotify Ltd