1 /*
2  * Copyright (c) 2013 Andrew Kelley
3  *
4  * This file is part of libgroove, which is MIT licensed.
5  * See http://opensource.org/licenses/MIT
6  */
7 
8 #ifndef GROOVE_FINGERPRINTER_H_INCLUDED
9 #define GROOVE_FINGERPRINTER_H_INCLUDED
10 
11 #include <groove/groove.h>
12 
13 #ifdef __cplusplus
14 extern "C"
15 {
16 #endif /* __cplusplus */
17 
18 /* use this to find out the unique id of an audio track */
19 
20 struct GrooveFingerprinterInfo {
21     /* raw fingerprint. A fingerprint is an array of signed 32-bit integers. */
22     int32_t *fingerprint;
23     /* the number of 32-bit integers in the fingerprint array */
24     int fingerprint_size;
25 
26     /* how many seconds long this song is */
27     double duration;
28 
29     /* the playlist item that this info applies to.
30      * When this is NULL this is the end-of-playlist sentinel and
31      * other properties are undefined.
32      */
33     struct GroovePlaylistItem *item;
34 };
35 
36 struct GrooveFingerprinter {
37     /* maximum number of GrooveFingerprinterInfo items to store in this
38      * fingerprinter's queue. this defaults to MAX_INT, meaning that
39      * the fingerprinter will cause the decoder to decode the entire
40      * playlist. if you want to instead, for example, obtain fingerprints
41      * at the same time as playback, you might set this value to 1.
42      */
43     int info_queue_size;
44 
45     /* how big the sink buffer should be, in sample frames.
46      * groove_fingerprinter_create defaults this to 8192
47      */
48     int sink_buffer_size;
49 
50     /* read-only. set when attached and cleared when detached */
51     struct GroovePlaylist *playlist;
52 };
53 
54 struct GrooveFingerprinter *groove_fingerprinter_create(void);
55 void groove_fingerprinter_destroy(struct GrooveFingerprinter *printer);
56 
57 /* once you attach, you must detach before destroying the playlist */
58 int groove_fingerprinter_attach(struct GrooveFingerprinter *printer,
59         struct GroovePlaylist *playlist);
60 int groove_fingerprinter_detach(struct GrooveFingerprinter *printer);
61 
62 /* returns < 0 on error, 0 on aborted (block=1) or no info ready (block=0),
63  * 1 on info returned.
64  * When you get info you must free it with groove_fingerprinter_free_info.
65  */
66 int groove_fingerprinter_info_get(struct GrooveFingerprinter *printer,
67         struct GrooveFingerprinterInfo *info, int block);
68 
69 void groove_fingerprinter_free_info(struct GrooveFingerprinterInfo *info);
70 
71 /* returns < 0 on error, 0 on no info ready, 1 on info ready
72  * if block is 1, block until info is ready
73  */
74 int groove_fingerprinter_info_peek(struct GrooveFingerprinter *printer,
75         int block);
76 
77 /* get the position of the printer head
78  * both the current playlist item and the position in seconds in the playlist
79  * item are given. item will be set to NULL if the playlist is empty
80  * you may pass NULL for item or seconds
81  */
82 void groove_fingerprinter_position(struct GrooveFingerprinter *printer,
83         struct GroovePlaylistItem **item, double *seconds);
84 
85 /**
86  * Compress and base64-encode a raw fingerprint
87  *
88  * The caller is responsible for freeing the returned pointer using
89  * groove_fingerprinter_dealloc().
90  *
91  * Parameters:
92  *  - fp: pointer to an array of signed 32-bit integers representing the raw
93  *        fingerprint to be encoded
94  *  - size: number of items in the raw fingerprint
95  *  - encoded_fp: pointer to a pointer, where the encoded fingerprint will be
96  *                stored
97  *
98  * Returns:
99  *  - 0 on success, < 0 on error
100  */
101 int groove_fingerprinter_encode(int32_t *fp, int size, char **encoded_fp);
102 
103 /**
104  * Uncompress and base64-decode an encoded fingerprint
105  *
106  * The caller is responsible for freeing the returned pointer using
107  * groove_fingerprinter_dealloc().
108  *
109  * Parameters:
110  *  - encoded_fp: Pointer to an encoded fingerprint
111  *  - encoded_size: Size of the encoded fingerprint in bytes
112  *  - fp: Pointer to a pointer, where the decoded raw fingerprint (array
113  *        of signed 32-bit integers) will be stored
114  *  - size: Number of items in the returned raw fingerprint
115  *
116  * Returns:
117  *  - 0 on success, < 0 on error
118  */
119 int groove_fingerprinter_decode(char *encoded_fp, int32_t **fp, int *size);
120 
121 void groove_fingerprinter_dealloc(void *ptr);
122 
123 #ifdef __cplusplus
124 }
125 #endif /* __cplusplus */
126 
127 #endif /* GROOVE_FINGERPRINTER_H_INCLUDED */
128