src/decoder_api.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 /*! \file
  21  * \brief The MPD Decoder API
  22  *
  23  * This is the public API which is used by decoder plugins to
  24  * communicate with the mpd core.
  25  */
  26
  27 #ifndef MPD_DECODER_API_H
  28 #define MPD_DECODER_API_H
  29
  30 #include "check.h"
  31 #include "decoder_command.h"
  32 #include "decoder_plugin.h"
  33 #include "input_stream.h"
  34 #include "replay_gain_info.h"
  35 #include "tag.h"
  36 #include "audio_format.h"
  37 #include "conf.h"
  38
  39 #include <stdbool.h>
  40
  41 /**
  42  * Notify the player thread that it has finished initialization and
  43  * that it has read the song's meta data.
  44  *
  45  * @param decoder the decoder object
  46  * @param audio_format the audio format which is going to be sent to
  47  * decoder_data()
  48  * @param seekable true if the song is seekable
  49  * @param total_time the total number of seconds in this song; -1 if unknown
  50  */
  51 void
  52 decoder_initialized(struct decoder *decoder,
  53                     const struct audio_format *audio_format,
  54                     bool seekable, float total_time);
  55
  56 /**
  57  * Determines the pending decoder command.
  58  *
  59  * @param decoder the decoder object
  60  * @return the current command, or DECODE_COMMAND_NONE if there is no
  61  * command pending
  62  */
  63 enum decoder_command
  64 decoder_get_command(struct decoder *decoder);
  65
  66 /**
  67  * Called by the decoder when it has performed the requested command
  68  * (dc->command).  This function resets dc->command and wakes up the
  69  * player thread.
  70  *
  71  * @param decoder the decoder object
  72  */
  73 void
  74 decoder_command_finished(struct decoder *decoder);
  75
  76 /**
  77  * Call this when you have received the DECODE_COMMAND_SEEK command.
  78  *
  79  * @param decoder the decoder object
  80  * @return the destination position for the week
  81  */
  82 double
  83 decoder_seek_where(struct decoder *decoder);
  84
  85 /**
  86  * Call this right before decoder_command_finished() when seeking has
  87  * failed.
  88  *
  89  * @param decoder the decoder object
  90  */
  91 void
  92 decoder_seek_error(struct decoder *decoder);
  93
  94 /**
  95  * Blocking read from the input stream.
  96  *
  97  * @param decoder the decoder object
  98  * @param is the input stream to read from
  99  * @param buffer the destination buffer
 100  * @param length the maximum number of bytes to read
 101  * @return the number of bytes read, or 0 if one of the following
 102  * occurs: end of file; error; command (like SEEK or STOP).
 103  */
 104 size_t
 105 decoder_read(struct decoder *decoder, struct input_stream *is,
 106              void *buffer, size_t length);
 107
 108 /**
 109  * Sets the time stamp for the next data chunk [seconds].  The MPD
 110  * core automatically counts it up, and a decoder plugin only needs to
 111  * use this function if it thinks that adding to the time stamp based
 112  * on the buffer size won't work.
 113  */
 114 void
 115 decoder_timestamp(struct decoder *decoder, double t);
 116
 117 /**
 118  * This function is called by the decoder plugin when it has
 119  * successfully decoded block of input data.
 120  *
 121  * @param decoder the decoder object
 122  * @param is an input stream which is buffering while we are waiting
 123  * for the player
 124  * @param data the source buffer
 125  * @param length the number of bytes in the buffer
 126  * @return the current command, or DECODE_COMMAND_NONE if there is no
 127  * command pending
 128  */
 129 enum decoder_command
 130 decoder_data(struct decoder *decoder, struct input_stream *is,
 131              const void *data, size_t length,
 132              uint16_t kbit_rate);
 133
 134 /**
 135  * This function is called by the decoder plugin when it has
 136  * successfully decoded a tag.
 137  *
 138  * @param decoder the decoder object
 139  * @param is an input stream which is buffering while we are waiting
 140  * for the player
 141  * @param tag the tag to send
 142  * @return the current command, or DECODE_COMMAND_NONE if there is no
 143  * command pending
 144  */
 145 enum decoder_command
 146 decoder_tag(struct decoder *decoder, struct input_stream *is,
 147             const struct tag *tag);
 148
 149 /**
 150  * Set replay gain values for the following chunks.
 151  *
 152  * @param decoder the decoder object
 153  * @param rgi the replay_gain_info object; may be NULL to invalidate
 154  * the previous replay gain values
 155  */
 156 void
 157 decoder_replay_gain(struct decoder *decoder,
 158                     const struct replay_gain_info *replay_gain_info);
 159
 160 /**
 161  * Store MixRamp tags.
 162  *
 163  * @param decoder the decoder object
 164  * @param mixramp_start the mixramp_start tag; may be NULL to invalidate
 165  * @param mixramp_end the mixramp_end tag; may be NULL to invalidate
 166  */
 167 void
 168 decoder_mixramp(struct decoder *decoder,
 169                 char *mixramp_start, char *mixramp_end);
 170
 171 #endif