Musly
An open-source audio music similarity library
Macros | Functions
musly.h File Reference
#include <musly/musly_types.h>

Go to the source code of this file.

Macros

#define MUSLY_EXPORT
 

Functions

MUSLY_EXPORT const char * musly_version ()
 Return the version of Musly. More...
 
MUSLY_EXPORT void musly_debug (int level)
 Set the musly debug level. More...
 
MUSLY_EXPORT const char * musly_jukebox_listmethods ()
 Lists all available music similarity methods. More...
 
MUSLY_EXPORT const char * musly_jukebox_listdecoders ()
 Lists all available audio file decoders. More...
 
MUSLY_EXPORT const char * musly_jukebox_aboutmethod (musly_jukebox *jukebox)
 Describe the initialized method. More...
 
MUSLY_EXPORT musly_jukeboxmusly_jukebox_poweron (const char *method, const char *decoder)
 Returns a reference to an initialized Musly jukebox object. More...
 
MUSLY_EXPORT void musly_jukebox_poweroff (musly_jukebox *jukebox)
 Deinitializes the given Musly jukebox. More...
 
MUSLY_EXPORT int musly_jukebox_setmusicstyle (musly_jukebox *jukebox, musly_track **tracks, int num_tracks)
 Initialize the jukebox music style. More...
 
MUSLY_EXPORT int musly_jukebox_addtracks (musly_jukebox *jukebox, musly_track **tracks, musly_trackid *trackids, int num_tracks)
 Add tracks to the Musly jukebox. More...
 
MUSLY_EXPORT int musly_jukebox_similarity (musly_jukebox *jukebox, musly_track *seed_track, musly_trackid seed_trackid, musly_track **tracks, musly_trackid *trackids, int num_tracks, float *similarities)
 Computes the similarity between a seed track and a list of other music tracks. More...
 
int musly_jukebox_guessneighbors (musly_jukebox *jukebox, musly_trackid seed, musly_trackid *neighbors, int num_neighbors)
 Tries to guess the most similar neighbors to the given trackid. More...
 
MUSLY_EXPORT musly_trackmusly_track_alloc (musly_jukebox *jukebox)
 Allocates a musly_track in memory. More...
 
MUSLY_EXPORT void musly_track_free (musly_track *track)
 Frees a musly_track previously allocated with musly_track_alloc(). More...
 
MUSLY_EXPORT int musly_track_size (musly_jukebox *jukebox)
 Returns the size of a musly_track in bytes. More...
 
MUSLY_EXPORT int musly_track_binsize (musly_jukebox *jukebox)
 Returns the buffer size in bytes required to hold a musly_track. More...
 
MUSLY_EXPORT int musly_track_tobin (musly_jukebox *jukebox, musly_track *from_track, unsigned char *to_buffer)
 Serializes a musly_track to a byte buffer. More...
 
MUSLY_EXPORT int musly_track_frombin (musly_jukebox *jukebox, unsigned char *from_buffer, musly_track *to_track)
 Deserializes a byte buffer to a musly_track. More...
 
const char * musly_track_tostr (musly_jukebox *jukebox, musly_track *from_track)
 This function displays a string representation of the given musly_track. More...
 
MUSLY_EXPORT int musly_track_analyze_pcm (musly_jukebox *jukebox, float *mono_22khz_pcm, int length_pcm, musly_track *track)
 Compute a music similarity model (musly_track) from the given PCM signal. More...
 
MUSLY_EXPORT int musly_track_analyze_audiofile (musly_jukebox *jukebox, const char *audiofile, int max_seconds, musly_track *track)
 Compute a music similarity model (musly_track) from the audio file. More...
 

Macro Definition Documentation

#define MUSLY_EXPORT

Function Documentation

MUSLY_EXPORT void musly_debug ( int  level)

Set the musly debug level.

Valid levels are 0 (Quiet, DEFAULT), 1 (Error), 2 (Warning), 3 (Info), 4 (Debug), 5 (Trace). All output will be sent to stderr.

Parameters
[in]levelThe musly library debug level, if the level is invalid it will be set to the closest valid level.
MUSLY_EXPORT const char* musly_jukebox_aboutmethod ( musly_jukebox jukebox)

Describe the initialized method.

This call describes the used music similarity method of the referenced musly_jukebox in more detail.

Parameters
[in]jukeboxan initialized reference to a Musly jukebox.
Returns
a description of the currently initialized music similarity method as a null terminated string.
See Also
musly_jukebox_poweron()
MUSLY_EXPORT int musly_jukebox_addtracks ( musly_jukebox jukebox,
musly_track **  tracks,
musly_trackid trackids,
int  num_tracks 
)

Add tracks to the Musly jukebox.

To use the music similarity routines each Musly track has to be added to a jukebox. Internally Musly allocates an initialization vector for each track computed with the tracks passed to musly_jukebox_setmusicstyle().

Parameters
[in]jukeboxthe Musly jukebox to add the track to.
[in]tracksan array of musly_track objects to add to the jukebox.
[out]trackidsthe track identifiers assigned by musly. The first track will have an id of 0 with the numbers increasing subsequently.
[in]num_tracksthe length of the tracks and trackids array.
Returns
0 on success -1 on an error. When an error is returned no track was added to Musly.
See Also
musly_jukebox_setmusicstyle(), musly_jukebox_similarity()
int musly_jukebox_guessneighbors ( musly_jukebox jukebox,
musly_trackid  seed,
musly_trackid neighbors,
int  num_neighbors 
)

Tries to guess the most similar neighbors to the given trackid.

If similarity measures implement this call, it is usually a very efficient way to pre-filter the whole jukebox collection for possible matches (neighbors) to the query song (seed). The musly_tracks do not have to be loaded to memory to use that call. It operates solely on an index usually built when adding the track to the jukebox (musly_jukebox_addtrack()). A maximum of num_neighbors is written in the neighbors list of track ids. The returned neighbors can be used to drastically reduce the number of input tracks (and thus computation time) for musyl_jukebox_similarity(). If the method is not implemented or all neighbors should be analyzed, -1 is returned. In that case consider all musly_tracks as possible nearest neighbors and thus as input to musly_jukebox_similarity().

Parameters
[in]jukeboxAn initialized Musly jukebox object with tracks added through musly_jukebox_addtrack().
[in]seedThe seed track id to search for its nearest neighbors.
[out]neighborsThe neighbors will be written to this preallocated array.
[in]num_neighborsThe maximum number of neighbors to write to the neighbors array.
Returns
the number of neighbors found for the given seed trackid (success). -1 is returned on a failure.
See Also
musly_jukebox_similarity(), musly_jukebox_addtrack().
MUSLY_EXPORT const char* musly_jukebox_listdecoders ( )

Lists all available audio file decoders.

The decoders are returned as a single null terminated string. The decoders are separated by a comma (,). Use a decoder name to power on a Musly jukebox musly_jukebox_poweron() The decoders are used in musly_track_analyze_audiofile().

Returns
all available audio file decoders.
See Also
musly_jukebox_poweron()
MUSLY_EXPORT const char* musly_jukebox_listmethods ( )

Lists all available music similarity methods.

The methods are returned as a single null terminated string. The methods are separated by a comma (,). Use a method name to power on a Musly jukebox.

Returns
all available methods
See Also
musly_jukebox_poweron()
MUSLY_EXPORT void musly_jukebox_poweroff ( musly_jukebox jukebox)

Deinitializes the given Musly jukebox.

The referenced method and decoder objects are freed. Previously allocated Musly tracks allocated with musly_track_alloc() need to be freed separately. The referenced Musly jukebox object is invalidated by this call.

Parameters
[in]jukeboxthe Musly jukebox to deinitialize.
See Also
musly_jukebox_poweron()
MUSLY_EXPORT musly_jukebox* musly_jukebox_poweron ( const char *  method,
const char *  decoder 
)

Returns a reference to an initialized Musly jukebox object.

To initialize Musly you need to specify a music similarity method to use and a decoder. You can set both values to 0 (NULL) to initialize the default method and decoder. To list all available music similarity methods use musly_jukebox_listmethods(). To list all available audio file decoders use musly_jukebox_listdecoders(). If the initialization fails, NULL is returned. To get more information about the initialized music similarity method use musly_jukebox_aboutmethod().

The returned reference is required for almost all subsequent calls to Musly library calls. To add a music track to the jukebox inventory use musly_jukebox_addtracks(). To compute recommendations with the jukebox use musly_jukebox_similarity(). Note that before computation of similarity, the music style needs to be set with musly_jukebox_setmusicstyle().

Parameters
[in]methodthe desired music similarity method.
[in]decoderthe desired decoder to initialize.
Returns
a reference to an initialized Musly jukebox object.
See Also
musly_jukebox_poweroff(), musly_jukebox_addtracks(), musly_jukebox_setmusicstyle(), musly_jukebox_similarity()
MUSLY_EXPORT int musly_jukebox_setmusicstyle ( musly_jukebox jukebox,
musly_track **  tracks,
int  num_tracks 
)

Initialize the jukebox music style.

To properly use the similarity function it is necessary to give the algorithms a hint about the music we are working with. Do this by passing a random sample of the tracks you want to analyze. As a rule of thumb use a maximum of 1000 randomly selected tracks to set the music style. The a copy of the musly_track array is stored internally. The referenced array can be safely deallocated after the call if required.

Parameters
[in]jukeboxthe Musly jukebox to set the music stlye.
[in]tracksa random sample array of Musly tracks to use for the initialization.
[in]num_tracksthe number of Musly tracks.
See Also
musly_jukebox_poweron(), musly_track_analyze_pcm(), musly_track_analyze_audiofile()
MUSLY_EXPORT int musly_jukebox_similarity ( musly_jukebox jukebox,
musly_track seed_track,
musly_trackid  seed_trackid,
musly_track **  tracks,
musly_trackid trackids,
int  num_tracks,
float *  similarities 
)

Computes the similarity between a seed track and a list of other music tracks.

To compute similarities between two music tracks the following steps have to been taken:

Parameters
[in]jukeboxThe Musly jukebox to use.
[in]seed_trackThe seed track to compute similarities to
[in]seed_trackidThe id of the seed track as returned by musly_jukebox_addtracks().
[in]tracksAn array of musly_track objects to compute the similarities to.
[in]trackidsAn array of musly_trackids corresponding to the tracks array. The musly_trackids are returned after adding them to the musly_jukebox
[in]num_tracksthe size of the tracks and trackids arrays
[out]similaritiesa preallocated float array to hold the computed similarities.
Returns
0 on success and -1 on an error.
See Also
musly_jukebox_poweron(), musly_track_analyze_audiofile(), musly_track_analyze_pcm(), musly_jukebox_setmusicstyle(), musly_jukebox_addtracks()
MUSLY_EXPORT musly_track* musly_track_alloc ( musly_jukebox jukebox)

Allocates a musly_track in memory.

As the size of a musly_track varies for each music similarity method, an initialized Musly jukebox object reference needs to be passed argument. You need to free the allocated musly_track with musly_track_free().

Parameters
[in]jukeboxA reference to an initialized Musly jukebox object.
Returns
An allocated musly_track float array.
See Also
musly_track_free()
MUSLY_EXPORT int musly_track_analyze_audiofile ( musly_jukebox jukebox,
const char *  audiofile,
int  max_seconds,
musly_track track 
)

Compute a music similarity model (musly_track) from the audio file.

The audio file is decoded with the decoder selected when initializing the musly_jukebox, down- and re-sampled to a 22050Hz mono signal before a musly_track is computed. The audio is analyzed according to the initialized music similarity method and the musly_track is filled with the feature data. To compute the similarity to other musly_track objects, use the musly_jukebox_similarity() function. If you already decoded the PCM signal of the music you want to analyze, use musly_track_analyze_pcm(). NOTE: Currently the central 30 seconds of each decoded pcm input are hardcoded to be used as input for the subsequent audio analysis functions.

Parameters
[in]jukeboxA reference to an initialized musly_jukebox object.
[in]audiofileAn audio file. The file will be decoded with the audio decoder.
[in]max_secondsThe maximum number of seconds to decode. If set to zero the whole audio file is decoded.
[out]trackThe musly_track to write the music similarity features.
Returns
0 on success, -1 on failure.
See Also
musly_track_analyze_audiofile(), musly_jukebox_poweron().
MUSLY_EXPORT int musly_track_analyze_pcm ( musly_jukebox jukebox,
float *  mono_22khz_pcm,
int  length_pcm,
musly_track track 
)

Compute a music similarity model (musly_track) from the given PCM signal.

The audio is analyzed according to the initialized music similarity method and the musly_track is filled with the feature data. The musly_track can then be used to compute the music similarity between other musly_track features (use musly_jukebox_similarity()). If you are analyzing music files, use musly_track_analyze_audiofile() which does the decoding and down-/re-sampling of audio itself.

Parameters
[in]jukeboxA reference to an initialized musly_jukebox object.
[in]mono_22khz_pcmThe audio signal to analyze represented as a PCM float array. The audio signal has to be mono and sampled at 22050hz with float values between -1.0 and +1.0.
[in]length_pcmThe length of the input float array.
[out]trackThe musly_track to write the music similarity features.
Returns
0 on success, -1 on failure.
See Also
musly_track_analyze_audiofile(), musly_jukebox_poweron().
MUSLY_EXPORT int musly_track_binsize ( musly_jukebox jukebox)

Returns the buffer size in bytes required to hold a musly_track.

To serialize a musly_track for persistent use musly_track_tobin(). The buffer size varies for each music similarity method.

Parameters
[in]jukeboxA reference to an initialized musly_jukebox object.
Returns
The required minimum buffer size required to hold a musly_track.
See Also
musly_jukebox_poweron(), musly_track_tobin(), musly_track_frombin().
MUSLY_EXPORT void musly_track_free ( musly_track track)

Frees a musly_track previously allocated with musly_track_alloc().

Parameters
[in]trackThe musly track you want to free.
See Also
musly_track_alloc()
MUSLY_EXPORT int musly_track_frombin ( musly_jukebox jukebox,
unsigned char *  from_buffer,
musly_track to_track 
)

Deserializes a byte buffer to a musly_track.

Use this method re-transform a previously serialized byte buffer (musly_track_tobin()) to a musly_track. From the buffer musly_track_binsize() bytes will be read.

Parameters
[in]jukeboxA reference to an initialized musly_jukebox object.
[in]from_bufferthe buffer to use for deserialization
[out]to_trackthe musyl_track to store the deserialized track.
Returns
The number of bytes read (musly_track_binsize()) in case of success, -1 in case an error occurred.
See Also
musly_jukebox_poweron(), musly_track_binsize(), musly_track_tobin().
MUSLY_EXPORT int musly_track_size ( musly_jukebox jukebox)

Returns the size of a musly_track in bytes.

In case you want to allocate the musly_track yourself, allocate the memory and cast the memory to a musly_track. The size of each musly_track varies from music similarity method to method, that is, the size depends on the method musly has been initialized with (musly_jukebox_poweron()). For safe serializing and deserializing of a musly_track to/from memory use musly_track_tobin() and musly_track_frombin().

Parameters
[in]jukeboxA reference to an initialized musly_jukebox object.
Returns
The number of bytes of a musly_track for the given musly_jukebox.
See Also
musly_jukebox_poweron(), musly_track_tobin(), musly_track_frombin().
MUSLY_EXPORT int musly_track_tobin ( musly_jukebox jukebox,
musly_track from_track,
unsigned char *  to_buffer 
)

Serializes a musly_track to a byte buffer.

Use this method to store or transmit a musly_track. musly_track_binsize() bytes will be written to to_buffer. To deserialize a buffer use musly_track_frombin().

Parameters
[in]jukeboxA reference to an initialized musly_jukebox object.
[in]from_trackThe track to serialize
[out]to_bufferThe buffer receiving the serialized track. The buffer needs to be preallocated with musly_track_binsize() bytes.
Returns
The number of bytes written (musly_track_binsize()) in case of success, -1 in case an error occurred.
See Also
musly_jukebox_poweron(), musly_track_binsize(), musly_track_frombin().
const char* musly_track_tostr ( musly_jukebox jukebox,
musly_track from_track 
)

This function displays a string representation of the given musly_track.

The data is displayed in a flat format. All data structures (matrices, covariance matrices) are exported as vectors. This call can be used to export the feature data for further analysis. Note: This function is not threadsafe!

Parameters
[in]jukeboxThe Musly jukenbox to use.
[in]from_trackthe musly_track to convert into a string representation.
Returns
a constant null terminated string representing from_track.
See Also
musly_track_tobin(), musly_track_frombin()
MUSLY_EXPORT const char* musly_version ( )

Return the version of Musly.

Returns
the version as a null terminated string.