Roc Toolkit internal modules
Roc Toolkit: real-time audio streaming
iframe_decoder.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2017 Roc authors
3  *
4  * This Source Code Form is subject to the terms of the Mozilla Public
5  * License, v. 2.0. If a copy of the MPL was not distributed with this
6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7  */
8 
9 //! @file roc_audio/iframe_decoder.h
10 //! @brief Audio frame decoder interface.
11 
12 #ifndef ROC_AUDIO_IFRAME_DECODER_H_
13 #define ROC_AUDIO_IFRAME_DECODER_H_
14 
15 #include "roc_audio/units.h"
16 #include "roc_core/stddefs.h"
17 #include "roc_packet/packet.h"
18 #include "roc_packet/units.h"
19 
20 namespace roc {
21 namespace audio {
22 
23 //! Audio frame decoder interface.
25 public:
26  virtual ~IFrameDecoder();
27 
28  //! Get decoded stream position.
29  //!
30  //! @returns
31  //! the position of the next sample that will be retrieved by read().
32  //!
33  //! @remarks
34  //! The decoded stream position is affected by begin(), read(), and shift() methods.
35  //! begin() changes it according to the provided frame position, however it depends
36  //! on the implementation how exactly. read() and shift() increase it by the number
37  //! of samples they returned.
38  virtual packet::timestamp_t position() const = 0;
39 
40  //! Get number of samples available for decoding.
41  //!
42  //! @returns
43  //! number of available samples per channel, or zero if there are no more
44  //! samples in the current frame, or if begin() was not called yet.
45  //!
46  //! @remarks
47  //! The number of samples available is affected by begin(), read(), and shift(),
48  //! and end() methods. begin() resets it according to the provided frame size,
49  //! however it depends on the implementation how exactly. end() resets it to zero.
50  //! read() and shift() decrease it by the number of samples they returned.
51  virtual packet::timestamp_t available() const = 0;
52 
53  //! Start decoding a new frame.
54  //!
55  //! @remarks
56  //! After this call, read() will retrieve samples from given @p frame_data, until
57  //! @p frame_size bytes are read or end() is called.
58  //!
59  //! @note
60  //! @p frame_position defines the position of the frame in the encoded stream.
61  //! Decoder updates the decoded stream possition according to @p frame_position,
62  //! but not necessary to the same value. Encoded and decoded stream positions
63  //! may be slightly different, depending on the codec implementation.
64  virtual void begin(packet::timestamp_t frame_position,
65  const void* frame_data,
66  size_t frame_size) = 0;
67 
68  //! Read samples from current frame.
69  //!
70  //! @b Parameters
71  //! - @p samples - buffer to write decoded samples to
72  //! - @p n_samples - number of samples to be decoded per channel
73  //! - @p channels - channel mask of the samples to be decoded
74  //!
75  //! @remarks
76  //! Decodes samples from the current frame and writes them to the provided buffer.
77  //!
78  //! @returns
79  //! number of samples decoded per channel. The returned value can be fewer than
80  //! @p n_samples if there are no more samples in the current frame.
81  //!
82  //! @pre
83  //! This method may be called only between begin() and end() calls.
84  //!
85  //! @note
86  //! Encoded and decoded channel masks may differ. If the decoded frame has
87  //! extra channels, they are ignored. If it doesn't have some channels, these
88  //! channels are filled with zeros.
89  virtual size_t
90  read(sample_t* samples, size_t n_samples, packet::channel_mask_t channels) = 0;
91 
92  //! Shift samples from current frame.
93  //!
94  //! @b Parameters
95  //! - @p n_samples - number of samples to shift per channel
96  //!
97  //! @remarks
98  //! Shifts the given number of samples from the left, as if read() was called
99  //! and the result was dropped.
100  //!
101  //! @returns
102  //! number of samples shifted per channel. The returned value can be fewer than
103  //! @p n_samples if there are no more samples in the current frame.
104  //!
105  //! @pre
106  //! This method may be called only between begin() and end() calls.
107  virtual size_t shift(size_t n_samples) = 0;
108 
109  //! Finish decoding current frame.
110  //!
111  //! @remarks
112  //! After this call, the frame can't be read or shifted anymore. A new frame
113  //! should be started by calling begin().
114  virtual void end() = 0;
115 };
116 
117 } // namespace audio
118 } // namespace roc
119 
120 #endif // ROC_AUDIO_IFRAME_DECODER_H_
virtual packet::timestamp_t position() const =0
Get decoded stream position.
virtual size_t read(sample_t *samples, size_t n_samples, packet::channel_mask_t channels)=0
Read samples from current frame.
virtual void end()=0
Finish decoding current frame.
Various units used in audio processing.
Root namespace.
float sample_t
Audio sample.
Definition: units.h:21
Audio frame decoder interface.
uint32_t channel_mask_t
Bitmask of channels present in audio packet.
Definition: units.h:77
virtual size_t shift(size_t n_samples)=0
Shift samples from current frame.
uint32_t timestamp_t
Audio packet timestamp.
Definition: units.h:46
Commonly used types and functions.
virtual void begin(packet::timestamp_t frame_position, const void *frame_data, size_t frame_size)=0
Start decoding a new frame.
Various units used in packets.
Packet.
virtual packet::timestamp_t available() const =0
Get number of samples available for decoding.