src/audio_format.h

   1 /*
   2  * Copyright (C) 2003-2010 The Music Player Daemon Project
   3  * http://www.musicpd.org
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18  */
  19
  20 #ifndef MPD_AUDIO_FORMAT_H
  21 #define MPD_AUDIO_FORMAT_H
  22
  23 #include <stdint.h>
  24 #include <stdbool.h>
  25
  26 enum sample_format {
  27         SAMPLE_FORMAT_UNDEFINED = 0,
  28
  29         SAMPLE_FORMAT_S8,
  30         SAMPLE_FORMAT_S16,
  31
  32         /**
  33          * Signed 24 bit integer samples, without padding.
  34          */
  35         SAMPLE_FORMAT_S24,
  36
  37         /**
  38          * Signed 24 bit integer samples, packed in 32 bit integers
  39          * (the most significant byte is filled with the sign bit).
  40          */
  41         SAMPLE_FORMAT_S24_P32,
  42
  43         SAMPLE_FORMAT_S32,
  44 };
  45
  46 /**
  47  * This structure describes the format of a raw PCM stream.
  48  */
  49 struct audio_format {
  50         /**
  51          * The sample rate in Hz.  A better name for this attribute is
  52          * "frame rate", because technically, you have two samples per
  53          * frame in stereo sound.
  54          */
  55         uint32_t sample_rate;
  56
  57         /**
  58          * The format samples are stored in.  See the #sample_format
  59          * enum for valid values.
  60          */
  61         uint8_t format;
  62
  63         /**
  64          * The number of channels.  Only mono (1) and stereo (2) are
  65          * fully supported currently.
  66          */
  67         uint8_t channels;
  68
  69         /**
  70          * If zero, then samples are stored in host byte order.  If
  71          * nonzero, then samples are stored in the reverse host byte
  72          * order.
  73          */
  74         uint8_t reverse_endian;
  75 };
  76
  77 /**
  78  * Buffer for audio_format_string().
  79  */
  80 struct audio_format_string {
  81         char buffer[24];
  82 };
  83
  84 /**
  85  * Clears the #audio_format object, i.e. sets all attributes to an
  86  * undefined (invalid) value.
  87  */
  88 static inline void audio_format_clear(struct audio_format *af)
  89 {
  90         af->sample_rate = 0;
  91         af->format = SAMPLE_FORMAT_UNDEFINED;
  92         af->channels = 0;
  93         af->reverse_endian = 0;
  94 }
  95
  96 /**
  97  * Initializes an #audio_format object, i.e. sets all
  98  * attributes to valid values.
  99  */
 100 static inline void audio_format_init(struct audio_format *af,
 101                                      uint32_t sample_rate,
 102                                      enum sample_format format, uint8_t channels)
 103 {
 104         af->sample_rate = sample_rate;
 105         af->format = (uint8_t)format;
 106         af->channels = channels;
 107         af->reverse_endian = 0;
 108 }
 109
 110 /**
 111  * Checks whether the specified #audio_format object has a defined
 112  * value.
 113  */
 114 static inline bool audio_format_defined(const struct audio_format *af)
 115 {
 116         return af->sample_rate != 0;
 117 }
 118
 119 /**
 120  * Checks whether the specified #audio_format object is full, i.e. all
 121  * attributes are defined.  This is more complete than
 122  * audio_format_defined(), but slower.
 123  */
 124 static inline bool
 125 audio_format_fully_defined(const struct audio_format *af)
 126 {
 127         return af->sample_rate != 0 && af->format != SAMPLE_FORMAT_UNDEFINED &&
 128                 af->channels != 0;
 129 }
 130
 131 /**
 132  * Checks whether the specified #audio_format object has at least one
 133  * defined value.
 134  */
 135 static inline bool
 136 audio_format_mask_defined(const struct audio_format *af)
 137 {
 138         return af->sample_rate != 0 || af->format != SAMPLE_FORMAT_UNDEFINED ||
 139                 af->channels != 0;
 140 }
 141
 142 /**
 143  * Checks whether the sample rate is valid.
 144  *
 145  * @param sample_rate the sample rate in Hz
 146  */
 147 static inline bool
 148 audio_valid_sample_rate(unsigned sample_rate)
 149 {
 150         return sample_rate > 0 && sample_rate < (1 << 30);
 151 }
 152
 153 /**
 154  * Checks whether the sample format is valid.
 155  *
 156  * @param bits the number of significant bits per sample
 157  */
 158 static inline bool
 159 audio_valid_sample_format(enum sample_format format)
 160 {
 161         switch (format) {
 162         case SAMPLE_FORMAT_S8:
 163         case SAMPLE_FORMAT_S16:
 164         case SAMPLE_FORMAT_S24:
 165         case SAMPLE_FORMAT_S24_P32:
 166         case SAMPLE_FORMAT_S32:
 167                 return true;
 168
 169         case SAMPLE_FORMAT_UNDEFINED:
 170                 break;
 171         }
 172
 173         return false;
 174 }
 175
 176 /**
 177  * Checks whether the number of channels is valid.
 178  */
 179 static inline bool
 180 audio_valid_channel_count(unsigned channels)
 181 {
 182         return channels >= 1 && channels <= 8;
 183 }
 184
 185 /**
 186  * Returns false if the format is not valid for playback with MPD.
 187  * This function performs some basic validity checks.
 188  */
 189 static inline bool audio_format_valid(const struct audio_format *af)
 190 {
 191         return audio_valid_sample_rate(af->sample_rate) &&
 192                 audio_valid_sample_format((enum sample_format)af->format) &&
 193                 audio_valid_channel_count(af->channels);
 194 }
 195
 196 /**
 197  * Returns false if the format mask is not valid for playback with
 198  * MPD.  This function performs some basic validity checks.
 199  */
 200 static inline bool audio_format_mask_valid(const struct audio_format *af)
 201 {
 202         return (af->sample_rate == 0 ||
 203                 audio_valid_sample_rate(af->sample_rate)) &&
 204                 (af->format == SAMPLE_FORMAT_UNDEFINED ||
 205                  audio_valid_sample_format((enum sample_format)af->format)) &&
 206                 (af->channels == 0 || audio_valid_channel_count(af->channels));
 207 }
 208
 209 static inline bool audio_format_equals(const struct audio_format *a,
 210                                        const struct audio_format *b)
 211 {
 212         return a->sample_rate == b->sample_rate &&
 213                 a->format == b->format &&
 214                 a->channels == b->channels &&
 215                 a->reverse_endian == b->reverse_endian;
 216 }
 217
 218 static inline void
 219 audio_format_mask_apply(struct audio_format *af,
 220                         const struct audio_format *mask)
 221 {
 222         if (mask->sample_rate != 0)
 223                 af->sample_rate = mask->sample_rate;
 224
 225         if (mask->format != SAMPLE_FORMAT_UNDEFINED)
 226                 af->format = mask->format;
 227
 228         if (mask->channels != 0)
 229                 af->channels = mask->channels;
 230 }
 231
 232 /**
 233  * Returns the size of each (mono) sample in bytes.
 234  */
 235 static inline unsigned audio_format_sample_size(const struct audio_format *af)
 236 {
 237         switch (af->format) {
 238         case SAMPLE_FORMAT_S8:
 239                 return 1;
 240
 241         case SAMPLE_FORMAT_S16:
 242                 return 2;
 243
 244         case SAMPLE_FORMAT_S24:
 245                 return 3;
 246
 247         case SAMPLE_FORMAT_S24_P32:
 248         case SAMPLE_FORMAT_S32:
 249                 return 4;
 250
 251         case SAMPLE_FORMAT_UNDEFINED:
 252                 break;
 253         }
 254
 255         return 0;
 256 }
 257
 258 /**
 259  * Returns the size of each full frame in bytes.
 260  */
 261 static inline unsigned
 262 audio_format_frame_size(const struct audio_format *af)
 263 {
 264         return audio_format_sample_size(af) * af->channels;
 265 }
 266
 267 /**
 268  * Returns the floating point factor which converts a time span to a
 269  * storage size in bytes.
 270  */
 271 static inline double audio_format_time_to_size(const struct audio_format *af)
 272 {
 273         return af->sample_rate * audio_format_frame_size(af);
 274 }
 275
 276 /**
 277  * Renders a #sample_format enum into a string, e.g. for printing it
 278  * in a log file.
 279  *
 280  * @param format a #sample_format enum value
 281  * @return the string
 282  */
 283 const char *
 284 sample_format_to_string(enum sample_format format);
 285
 286 /**
 287  * Renders the #audio_format object into a string, e.g. for printing
 288  * it in a log file.
 289  *
 290  * @param af the #audio_format object
 291  * @param s a buffer to print into
 292  * @return the string, or NULL if the #audio_format object is invalid
 293  */
 294 const char *
 295 audio_format_to_string(const struct audio_format *af,
 296                        struct audio_format_string *s);
 297
 298 #endif