#include <musly/musly_types.h>

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_jukebox *	musly_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_track *	musly_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] level The 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] jukebox an 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]	jukebox	the Musly jukebox to add the track to.
[in]	tracks	an array of musly_track objects to add to the jukebox.
[out]	trackids	the track identifiers assigned by musly. The first track will have an id of 0 with the numbers increasing subsequently.
[in]	num_tracks	the 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]	jukebox	An initialized Musly jukebox object with tracks added through musly_jukebox_addtrack().
[in]	seed	The seed track id to search for its nearest neighbors.
[out]	neighbors	The neighbors will be written to this preallocated array.
[in]	num_neighbors	The 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] jukebox the 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]	method	the desired music similarity method.
[in]	decoder	the 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]	jukebox	the Musly jukebox to set the music stlye.
[in]	tracks	a random sample array of Musly tracks to use for the initialization.
[in]	num_tracks	the 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:

initialize a musly_jukebox object with: musly_jukebox_poweron()
analyze audio files, e.g. with musly_track_analyze_audiofile()
set the music style of the jukebox by using a small random sample of the audio tracks analyzed: musly_jukebox_setmusicstyle()
add the audio tracks to the musly_jukebox: musly_jukebox_addtracks()
use this function to compute similarities.

Parameters

[in]	jukebox	The Musly jukebox to use.
[in]	seed_track	The seed track to compute similarities to
[in]	seed_trackid	The id of the seed track as returned by musly_jukebox_addtracks().
[in]	tracks	An array of musly_track objects to compute the similarities to.
[in]	trackids	An array of musly_trackids corresponding to the tracks array. The musly_trackids are returned after adding them to the musly_jukebox
[in]	num_tracks	the size of the tracks and trackids arrays
[out]	similarities	a 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] jukebox A 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]	jukebox	A reference to an initialized musly_jukebox object.
[in]	audiofile	An audio file. The file will be decoded with the audio decoder.
[in]	max_seconds	The maximum number of seconds to decode. If set to zero the whole audio file is decoded.
[out]	track	The 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]	jukebox	A reference to an initialized musly_jukebox object.
[in]	mono_22khz_pcm	The 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_pcm	The length of the input float array.
[out]	track	The 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] jukebox A 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] track The 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]	jukebox	A reference to an initialized musly_jukebox object.
[in]	from_buffer	the buffer to use for deserialization
[out]	to_track	the 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] jukebox A 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]	jukebox	A reference to an initialized musly_jukebox object.
[in]	from_track	The track to serialize
[out]	to_buffer	The 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]	jukebox	The Musly jukenbox to use.
[in]	from_track	the 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.

Macros

Functions

Macro Definition Documentation

Function Documentation