1/**
2 * Copyright (c) 2006-2023 LOVE Development Team
3 *
4 * This software is provided 'as-is', without any express or implied
5 * warranty. In no event will the authors be held liable for any damages
6 * arising from the use of this software.
7 *
8 * Permission is granted to anyone to use this software for any purpose,
9 * including commercial applications, and to alter it and redistribute it
10 * freely, subject to the following restrictions:
11 *
12 * 1. The origin of this software must not be misrepresented; you must not
13 * claim that you wrote the original software. If you use this software
14 * in a product, an acknowledgment in the product documentation would be
15 * appreciated but is not required.
16 * 2. Altered source versions must be plainly marked as such, and must not be
17 * misrepresented as being the original software.
18 * 3. This notice may not be removed or altered from any source distribution.
19 **/
20
21#ifndef LOVE_SOUND_DECODER_H
22#define LOVE_SOUND_DECODER_H
23
24// LOVE
25#include "common/Object.h"
26#include "filesystem/File.h"
27
28#include <string>
29
30namespace love
31{
32namespace sound
33{
34/**
35 * Decoder objects are responsible for decoding audio files. They maintain
36 * an interal buffer into which they write raw decoded audio data.
37 **/
38class Decoder : public Object
39{
40public:
41
42 static love::Type type;
43
44 Decoder(Data *data, int bufferSize);
45 virtual ~Decoder();
46
47 /**
48 * Indicates how many bytes of raw data should be generated at each
49 * call to Decode.
50 **/
51 static const int DEFAULT_BUFFER_SIZE = 16384;
52
53 /**
54 * Indicates the quality of the sound.
55 **/
56 static const int DEFAULT_SAMPLE_RATE = 44100;
57
58 /**
59 * Default is stereo.
60 **/
61 static const int DEFAULT_CHANNELS = 2;
62
63 /**
64 * 16 bit audio is the default.
65 **/
66 static const int DEFAULT_BIT_DEPTH = 16;
67
68 /**
69 * Creates a deep of itself. The sound stream can (and should) be
70 * rewound, and does not have to be at the same place.
71 * @return A new Decoder object.
72 **/
73 virtual Decoder *clone() = 0;
74
75 /**
76 * Decodes the next chunk of the music stream, this will usually be
77 * bufferSize amount of bytes, unless EOF occurs. Zero or negative values
78 * indicate EOF or errors.
79 * @return The number of bytes actually decoded.
80 **/
81 virtual int decode() = 0;
82
83 /**
84 * Gets the size of the buffer (NOT the size of the entire stream).
85 * @return The size of the buffer.
86 **/
87 virtual int getSize() const;
88
89 /**
90 * Gets a pointer to the actual data. The contents of this buffer will
91 * change with each call to decode, so the client must copy the data.
92 * @return A buffer to raw sound data.
93 **/
94 virtual void *getBuffer() const;
95
96 /**
97 * Seeks to the specified position, if possible.
98 * @param s The position in the stream in seconds.
99 * @return True if success, false on fail/unsupported.
100 **/
101 virtual bool seek(double s) = 0;
102
103 /**
104 * Rewinds the stream to the start.
105 * @return True if success, false on fail/unsupported.
106 **/
107 virtual bool rewind() = 0;
108
109 /**
110 * Checks whether a stream is seekable.
111 * @return True if seekable, false otherwise.
112 **/
113 virtual bool isSeekable() = 0;
114
115 /**
116 * Checks whether a stream has more data to decode or not. Use
117 * rewind to start the stream again.
118 * @return False if there is more data, true on EOF.
119 **/
120 virtual bool isFinished();
121
122 /**
123 * Gets the number of channels in a stream. Supported values are 1 (mono) or 2 (stereo).
124 * @return Either 1 for mono, 2 for stereo, or 0 on errors.
125 **/
126 virtual int getChannelCount() const = 0;
127
128 /**
129 * Gets the number of bits per sample. Supported values are 8 or 16.
130 * @return Either 8, 16, or 0 if unsupported.
131 **/
132 virtual int getBitDepth() const = 0;
133
134 /**
135 * Gets the sample rate for the Decoder, that is, samples per second.
136 * @return The sample rate, eg. 44100.
137 **/
138 virtual int getSampleRate() const;
139
140 /**
141 * Gets the estimated total duration of the stream. in seconds. May return
142 * -1 if the duration cannot be determined.
143 **/
144 virtual double getDuration() = 0;
145
146protected:
147
148 // The encoded data. This should be replaced with buffered file
149 // reads in the future.
150 StrongRef<Data> data;
151
152 // When the decoder decodes data incrementally, it writes
153 // this many bytes at a time (at most).
154 int bufferSize;
155
156 // The desired frequency of the samples. 44100, 22050, or 11025.
157 int sampleRate;
158
159 // Holds internal memory.
160 void *buffer;
161
162 // Set this to true when eof has been reached.
163 bool eof;
164
165}; // Decoder
166
167} // sound
168} // love
169
170#endif // LOVE_SOUND_DECODER_H
171