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_ENCODER_H_INCLUDED 9 #define GROOVE_ENCODER_H_INCLUDED 10 11 #include "groove.h" 12 13 #ifdef __cplusplus 14 extern "C" 15 { 16 #endif /* __cplusplus */ 17 18 /* attach a GrooveEncoder to a playlist to keep a buffer of encoded audio full. 19 * for example you could use it to implement an http audio stream 20 */ 21 22 struct GrooveEncoder { 23 /* The desired audio format to encode. 24 * groove_encoder_create defaults these to 44100 Hz, 25 * signed 16-bit int, stereo. 26 * These are preferences; if a setting cannot be used, a substitute will be 27 * used instead. actual_audio_format is set to the actual values. 28 */ 29 struct GrooveAudioFormat target_audio_format; 30 31 /* Select encoding quality by choosing a target bit rate in bits per 32 * second. Note that typically you see this expressed in "kbps", such 33 * as 320kbps or 128kbps. Surprisingly, in this circumstance 1 kbps is 34 * 1000 bps, *not* 1024 bps as you would expect. 35 * groove_encoder_create defaults this to 256000 36 */ 37 int bit_rate; 38 39 /* optional - choose a short name for the format 40 * to help libgroove guess which format to use 41 * use `avconv -formats` to get a list of possibilities 42 */ 43 const char *format_short_name; 44 /* optional - choose a short name for the codec 45 * to help libgroove guess which codec to use 46 * use `avconv -codecs` to get a list of possibilities 47 */ 48 const char *codec_short_name; 49 /* optional - provide an example filename 50 * to help libgroove guess which format/codec to use 51 */ 52 const char *filename; 53 /* optional - provide a mime type string 54 * to help libgroove guess which format/codec to use 55 */ 56 const char *mime_type; 57 58 /* how big the sink buffer should be, in sample frames. 59 * groove_encoder_create defaults this to 8192 60 */ 61 int sink_buffer_size; 62 63 /* how big the encoded audio buffer should be, in bytes 64 * groove_encoder_create defaults this to 16384 65 */ 66 int encoded_buffer_size; 67 68 /* This volume adjustment to make to this player. 69 * It is recommended that you leave this at 1.0 and instead adjust the 70 * gain of the underlying playlist. 71 * If you want to change this value after you have already attached the 72 * sink to the playlist, you must use groove_encoder_set_gain. 73 * float format. Defaults to 1.0 74 */ 75 double gain; 76 77 /* read-only. set when attached and cleared when detached */ 78 struct GroovePlaylist *playlist; 79 80 /* read-only. set to the actual format you get when you attach to a 81 * playlist. ideally will be the same as target_audio_format but might 82 * not be. 83 */ 84 struct GrooveAudioFormat actual_audio_format; 85 }; 86 87 struct GrooveEncoder *groove_encoder_create(void); 88 /* detach before destroying */ 89 void groove_encoder_destroy(struct GrooveEncoder *encoder); 90 91 /* once you attach, you must detach before destroying the playlist 92 * at playlist begin, format headers are generated. when end of playlist is 93 * reached, format trailers are generated. 94 */ 95 int groove_encoder_attach(struct GrooveEncoder *encoder, 96 struct GroovePlaylist *playlist); 97 int groove_encoder_detach(struct GrooveEncoder *encoder); 98 99 /* returns < 0 on error, GROOVE_BUFFER_NO on aborted (block=1) or no buffer 100 * ready (block=0), GROOVE_BUFFER_YES on buffer returned, and GROOVE_BUFFER_END 101 * on end of playlist. 102 * buffer is always set to either a valid GrooveBuffer or NULL. 103 */ 104 int groove_encoder_buffer_get(struct GrooveEncoder *encoder, 105 struct GrooveBuffer **buffer, int block); 106 107 /* returns < 0 on error, 0 on no buffer ready, 1 on buffer ready 108 * if block is 1, block until buffer is ready 109 */ 110 int groove_encoder_buffer_peek(struct GrooveEncoder *encoder, int block); 111 112 /* see docs for groove_file_metadata_get */ 113 struct GrooveTag *groove_encoder_metadata_get(struct GrooveEncoder *encoder, 114 const char *key, const struct GrooveTag *prev, int flags); 115 116 /* see docs for groove_file_metadata_set */ 117 int groove_encoder_metadata_set(struct GrooveEncoder *encoder, const char *key, 118 const char *value, int flags); 119 120 /* get the position of the encode head 121 * both the current playlist item and the position in seconds in the playlist 122 * item are given. item will be set to NULL if the playlist is empty 123 * you may pass NULL for item or seconds 124 */ 125 void groove_encoder_position(struct GrooveEncoder *encoder, 126 struct GroovePlaylistItem **item, double *seconds); 127 128 /* See the gain property of GrooveSink. It is recommended that you leave this 129 * at 1.0 and instead adjust the gain of the playlist. 130 * returns 0 on success, < 0 on error 131 */ 132 int groove_encoder_set_gain(struct GrooveEncoder *encoder, double gain); 133 134 #ifdef __cplusplus 135 } 136 #endif /* __cplusplus */ 137 138 #endif /* GROOVE_ENCODER_H_INCLUDED */ 139