chromaprint/package.d

   1 // Copyright (C) 2010-2016  Lukas Lalinsky
   2 // Distributed under the MIT license, see the LICENSE file for details.
   3 /**
   4  * Chromaprint:
   5  *
   6  * Introduction:
   7  *
   8  * Chromaprint is a library for generating audio fingerprints, mainly to be used with the <a href="https://acoustid.org">AcoustID</a> service.
   9  *<br><br>
  10  * It needs raw audio stream (16-bit signed int) on input. The audio can have any sampling rate and any number of channels. Typically,
  11  * you would use some native library for decoding compressed audio files and feed the result into Chromaprint.
  12  *<br><br>
  13  * Audio fingerprints returned from the library can be represented either as
  14  * base64-encoded strings or 32-bit integer arrays. The base64-encoded strings
  15  * are usually what's used externally when you need to send the fingerprint
  16  * to a service. You can't directly compare the fingerprints in such form.
  17  * The 32-bit integer arrays are also called "raw fingerprints" and they
  18  * represent the internal structure of the fingerprints. If you want to
  19  * compare two fingerprints yourself, you probably want them in this form.
  20  *<br><br>
  21  * Generating fingerprints:
  22  *<br><br>
  23  * Here is a simple example code that generates a fingerprint from audio samples in memory:
  24  *<br><br>
  25  * Example:
  26  * -------
  27  *     ChromaprintContext *ctx;
  28  *     char *fp;
  29  *
  30  *     const int sample_rate = 44100;
  31  *     const int num_channels = 2;
  32  *
  33  *     ctx = chromaprint_new(CHROMAPRINT_ALGORITHM_DEFAULT);
  34  *
  35  *     chromaprint_start(ctx, sample_rate, num_channels);
  36  *     while (has_more_data) {
  37  *         chromaprint_feed(ctx, data, size);
  38  *     }
  39  *     chromaprint_finish(ctx);
  40  *
  41  *     chromaprint_get_fingerprint(ctx, &fp);
  42  *     printf("%s\n", fp);
  43  *     chromaprint_dealloc(fp);
  44  *
  45  *     chromaprint_free(ctx);
  46  * -------
  47  *
  48  * Note that there is no error handling in the code above. Almost any of the called functions can fail.
  49  * You should check the return values in an actual code.
  50  */
  51 module iv.chromaprint /*is aliced*/;
  52 pragma(lib, "chromaprint");
  53 import iv.alice;
  54
  55 extern(C) nothrow @nogc:
  56
  57 struct ChromaprintContextPrivate {}
  58 alias ChromaprintContext = ChromaprintContextPrivate;
  59
  60 struct ChromaprintMatcherContextPrivate {}
  61 alias ChromaprintMatcherContext = ChromaprintMatcherContextPrivate;
  62
  63 enum CHROMAPRINT_VERSION_MAJOR = 1;
  64 enum CHROMAPRINT_VERSION_MINOR = 4;
  65 enum CHROMAPRINT_VERSION_PATCH = 1;
  66
  67 ///
  68 alias  ChromaprintAlgorithm = int;
  69 enum /*ChromaprintAlgorithm*/:int {
  70   CHROMAPRINT_ALGORITHM_TEST1 = 0, ///
  71   CHROMAPRINT_ALGORITHM_TEST2, ///
  72   CHROMAPRINT_ALGORITHM_TEST3, ///
  73   CHROMAPRINT_ALGORITHM_TEST4, ///
  74   CHROMAPRINT_ALGORITHM_TEST5, ///
  75   CHROMAPRINT_ALGORITHM_DEFAULT = CHROMAPRINT_ALGORITHM_TEST2, ///
  76 }
  77
  78 /**
  79  * Return the version number of Chromaprint.
  80  */
  81 /*CHROMAPRINT_API*/ const(char)* chromaprint_get_version ();
  82
  83 /**
  84  * Allocate and initialize the Chromaprint context.
  85  *
  86  * Note that when Chromaprint is compiled with FFTW, this function is
  87  * not reentrant and you need to call it only from one thread at a time.
  88  * This is not a problem when using FFmpeg or vDSP.
  89  *
  90  * Params:
  91  *   algorithm = the fingerprint algorithm version you want to use, or
  92  *    CHROMAPRINT_ALGORITHM_DEFAULT for the default algorithm
  93  *
  94  * Returns: Chromaprint context pointer
  95  */
  96 /*CHROMAPRINT_API*/ ChromaprintContext* chromaprint_new (int algorithm=CHROMAPRINT_ALGORITHM_DEFAULT);
  97
  98 /**
  99  * Deallocate the Chromaprint context.
 100  *
 101  * Note that when Chromaprint is compiled with FFTW, this function is
 102  * not reentrant and you need to call it only from one thread at a time.
 103  * This is not a problem when using FFmpeg or vDSP.
 104  *
 105  * params: ctx = Chromaprint context pointer
 106  */
 107 /*CHROMAPRINT_API*/ void chromaprint_free (ChromaprintContext* ctx);
 108
 109 /**
 110  * Return the fingerprint algorithm this context is configured to use.
 111  * params: ctx = Chromaprint context pointer
 112  * returns: current algorithm version
 113  */
 114 /*CHROMAPRINT_API*/ int chromaprint_get_algorithm (ChromaprintContext* ctx);
 115
 116 /**
 117  * Set a configuration option for the selected fingerprint algorithm.
 118  *
 119  * DO NOT USE THIS FUNCTION IF YOU ARE PLANNING TO USE
 120  * THE GENERATED FINGERPRINTS WITH THE ACOUSTID SERVICE.
 121  *<br><br>
 122  * Possible options:<br>
 123  *  - silence_threshold: threshold for detecting silence, 0-32767
 124  *
 125  * params:
 126  *   ctx = Chromaprint context pointer
 127  *   name = option name
 128  *   value = option value
 129  *
 130  * returns: 0 on error, 1 on success
 131  */
 132 /*CHROMAPRINT_API*/ int chromaprint_set_option (ChromaprintContext* ctx, const(char)* name, int value);
 133
 134 /**
 135  * Get the number of channels that is internally used for fingerprinting.
 136  *
 137  * Note: You normally don't need this. Just set the audio's actual number of channels
 138  * when calling chromaprint_start() and everything will work. This is only used for
 139  * certain optimized cases to control the audio source.
 140  *
 141  * params: ctx = Chromaprint context pointer
 142  *
 143  * returns: number of channels
 144  */
 145 /*CHROMAPRINT_API*/ int chromaprint_get_num_channels (ChromaprintContext* ctx);
 146
 147 /**
 148  * Get the sampling rate that is internally used for fingerprinting.
 149  *
 150  * Note: You normally don't need this. Just set the audio's actual number of channels
 151  * when calling chromaprint_start() and everything will work. This is only used for
 152  * certain optimized cases to control the audio source.
 153  *
 154  * params: ctx = Chromaprint context pointer
 155  *
 156  * returns: sampling rate
 157  */
 158 /*CHROMAPRINT_API*/ int chromaprint_get_sample_rate (ChromaprintContext* ctx);
 159
 160 /**
 161  * Get the duration of one item in the raw fingerprint in samples.
 162  *
 163  * params: ctx = Chromaprint context pointer
 164  *
 165  * returns: duration in samples
 166  */
 167 /*CHROMAPRINT_API*/ int chromaprint_get_item_duration (ChromaprintContext* ctx);
 168
 169 /**
 170  * Get the duration of one item in the raw fingerprint in milliseconds.
 171  *
 172  * params: ctx = Chromaprint context pointer
 173  *
 174  * returns: duration in milliseconds
 175  */
 176 /*CHROMAPRINT_API*/ int chromaprint_get_item_duration_ms (ChromaprintContext* ctx);
 177
 178 /**
 179  * Get the duration of internal buffers that the fingerprinting algorithm uses.
 180  *
 181  * params: ctx = Chromaprint context pointer
 182  *
 183  * returns: duration in samples
 184  */
 185 /*CHROMAPRINT_API*/ int chromaprint_get_delay (ChromaprintContext* ctx);
 186
 187 /**
 188  * Get the duration of internal buffers that the fingerprinting algorithm uses.
 189  *
 190  * params: ctx = Chromaprint context pointer
 191  *
 192  * returns: duration in milliseconds
 193  */
 194 /*CHROMAPRINT_API*/ int chromaprint_get_delay_ms (ChromaprintContext* ctx);
 195
 196 /**
 197  * Restart the computation of a fingerprint with a new audio stream.
 198  *
 199  * params:
 200  *   ctx = Chromaprint context pointer
 201  *   sample_rate = sample rate of the audio stream (in Hz)
 202  *   num_channels = numbers of channels in the audio stream (1 or 2)
 203  *
 204  * returns: 0 on error, 1 on success
 205  */
 206 /*CHROMAPRINT_API*/ int chromaprint_start (ChromaprintContext* ctx, int sample_rate, int num_channels);
 207
 208 /**
 209  * Send audio data to the fingerprint calculator.
 210  *
 211  * params:
 212  *   ctx = Chromaprint context pointer
 213  *   data = raw audio data, should point to an array of 16-bit signed integers in native byte-order
 214  *   size = size of the data buffer (in samples)
 215  *
 216  * returns: 0 on error, 1 on success
 217  */
 218 /*CHROMAPRINT_API*/ int chromaprint_feed (ChromaprintContext* ctx, const(short)* data, int size);
 219
 220 /**
 221  * Process any remaining buffered audio data.
 222  *
 223  * params: ctx = Chromaprint context pointer
 224  *
 225  * returns: 0 on error, 1 on success
 226  */
 227 /*CHROMAPRINT_API*/ int chromaprint_finish (ChromaprintContext* ctx);
 228
 229 /**
 230  * Return the calculated fingerprint as a compressed string.
 231  *
 232  * The caller is responsible for freeing the returned pointer using
 233  * chromaprint_dealloc().
 234  *
 235  * params:
 236  *   ctx = Chromaprint context pointer
 237  *   fingerprint = pointer to a pointer, where a pointer to the allocated array will be stored (out)
 238  *
 239  * returns: 0 on error, 1 on success
 240  */
 241 /*CHROMAPRINT_API*/ int chromaprint_get_fingerprint (ChromaprintContext* ctx, char** fingerprint);
 242
 243 /**
 244  * Return the calculated fingerprint as an array of 32-bit integers.
 245  *
 246  * The caller is responsible for freeing the returned pointer using
 247  * chromaprint_dealloc().
 248  *
 249  * params:
 250  *   ctx = Chromaprint context pointer
 251  *   fingerprint = pointer to a pointer, where a pointer to the allocated array will be stored (out)
 252  *   size = number of items in the returned raw fingerprint (out)
 253  *
 254  * returns: 0 on error, 1 on success
 255  */
 256 /*CHROMAPRINT_API*/ int chromaprint_get_raw_fingerprint(ChromaprintContext* ctx, uint** fingerprint, int* size);
 257
 258 /**
 259  * Return the length of the current raw fingerprint.
 260  *
 261  * params:
 262  *   ctx = Chromaprint context pointer
 263  *   size = number of items in the current raw fingerprint (out)
 264  *
 265  * returns: 0 on error, 1 on success
 266  */
 267 /*CHROMAPRINT_API*/ int chromaprint_get_raw_fingerprint_size (ChromaprintContext* ctx, int* size);
 268
 269 /**
 270  * Return 32-bit hash of the calculated fingerprint.
 271  *
 272  * See chromaprint_hash_fingerprint() for details on how to use the hash.
 273  *
 274  * params:
 275  *   ctx = Chromaprint context pointer
 276  *   hash = pointer to a 32-bit integer where the hash will be stored (out)
 277  *
 278  * returns: 0 on error, 1 on success
 279  */
 280 /*CHROMAPRINT_API*/ int chromaprint_get_fingerprint_hash (ChromaprintContext* ctx, uint* hash);
 281
 282 /**
 283  * Clear the current fingerprint, but allow more data to be processed.
 284  *
 285  * This is useful if you are processing a long stream and want to many
 286  * smaller fingerprints, instead of waiting for the entire stream to be
 287  * processed.
 288  *
 289  * params: ctx = Chromaprint context pointer
 290  *
 291  * returns: 0 on error, 1 on success
 292  */
 293 /*CHROMAPRINT_API*/ int chromaprint_clear_fingerprint (ChromaprintContext* ctx);
 294
 295 /**
 296  * Compress and optionally base64-encode a raw fingerprint
 297  *
 298  * The caller is responsible for freeing the returned pointer using
 299  * chromaprint_dealloc().
 300  *
 301  * params:
 302  *   fp = pointer to an array of 32-bit integers representing the raw fingerprint to be encoded
 303  *   size = number of items in the raw fingerprint
 304  *   algorithm = Chromaprint algorithm version which was used to generate the raw fingerprint
 305  *   encoded_fp = pointer to a pointer, where the encoded fingerprint will be stored (out)
 306  *   encoded_size = size of the encoded fingerprint in bytes (out)
 307  *   base64 = Whether to return binary data or base64-encoded ASCII data. The
 308  *            compressed fingerprint will be encoded using base64 with the
 309  *            URL-safe scheme if you set this parameter to 1. It will return
 310  *            binary data if it's 0.
 311  *
 312  * returns: 0 on error, 1 on success
 313  */
 314 /*CHROMAPRINT_API*/ int chromaprint_encode_fingerprint (const(uint)* fp, int size, int algorithm, char** encoded_fp, int* encoded_size, int base64);
 315
 316 /**
 317  * Uncompress and optionally base64-decode an encoded fingerprint
 318  *
 319  * The caller is responsible for freeing the returned pointer using
 320  * chromaprint_dealloc().
 321  *
 322  * params:
 323  *   encoded_fp = pointer to an encoded fingerprint
 324  *   encoded_size = size of the encoded fingerprint in bytes
 325  *   fp = pointer to a pointer, where the decoded raw fingerprint (array of 32-bit integers) will be stored (out)
 326  *   size = Number of items in the returned raw fingerprint (out)
 327  *   algorithm = Chromaprint algorithm version which was used to generate the raw fingerprint (out)
 328  *   base64 = Whether the encoded_fp parameter contains binary data or
 329  *            base64-encoded ASCII data. If 1, it will base64-decode the data
 330  *            before uncompressing the fingerprint.
 331  *
 332  * returns: 0 on error, 1 on success
 333  */
 334 /*CHROMAPRINT_API*/ int chromaprint_decode_fingerprint (const(char)* encoded_fp, int encoded_size, uint** fp, int* size, int* algorithm, int base64);
 335
 336 /**
 337  * Generate a single 32-bit hash for a raw fingerprint.
 338  *
 339  * If two fingerprints are similar, their hashes generated by this function
 340  * will also be similar. If they are significantly different, their hashes
 341  * will most likely be significantly different as well, but you can't rely
 342  * on that.
 343  *
 344  * You compare two hashes by counting the bits in which they differ. Normally
 345  * that would be something like POPCNT(hash1 XOR hash2), which returns a
 346  * number between 0 and 32. Anthing above 15 means the hashes are
 347  * completely different.
 348  *
 349  * params:
 350  *   fp = pointer to an array of 32-bit integers representing the raw fingerprint to be hashed
 351  *   size = number of items in the raw fingerprint
 352  *   hash = pointer to a 32-bit integer where the hash will be stored (out)
 353  *
 354  * returns: 0 on error, 1 on success
 355  */
 356 /*CHROMAPRINT_API*/ int chromaprint_hash_fingerprint(const(uint)* fp, int size, uint *hash);
 357
 358 /**
 359  * Free memory allocated by any function from the Chromaprint API.
 360  *
 361  * params: ptr = pointer to be deallocated
 362  */
 363 /*CHROMAPRINT_API*/ void chromaprint_dealloc(void *ptr);