1/*
2 *  Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
3 *
4 *  Use of this source code is governed by a BSD-style license
5 *  that can be found in the LICENSE file in the root of the source
6 *  tree. An additional intellectual property rights grant can be found
7 *  in the file PATENTS.  All contributing project authors may
8 *  be found in the AUTHORS file in the root of the source tree.
9 */
10
11#ifndef WEBRTC_MODULES_MEDIA_FILE_INTERFACE_MEDIA_FILE_H_
12#define WEBRTC_MODULES_MEDIA_FILE_INTERFACE_MEDIA_FILE_H_
13
14#include "webrtc/common_types.h"
15#include "webrtc/modules/interface/module.h"
16#include "webrtc/modules/interface/module_common_types.h"
17#include "webrtc/modules/media_file/interface/media_file_defines.h"
18#include "webrtc/typedefs.h"
19
20namespace webrtc {
21class MediaFile : public Module
22{
23public:
24    // Factory method. Constructor disabled. id is the identifier for the
25    // MediaFile instance.
26    static MediaFile* CreateMediaFile(const int32_t id);
27    static void DestroyMediaFile(MediaFile* module);
28
29    // Set the MediaFile instance identifier.
30    virtual int32_t ChangeUniqueId(const int32_t id) OVERRIDE = 0;
31
32    // Put 10-60ms of audio data from file into the audioBuffer depending on
33    // codec frame size. dataLengthInBytes is both an input and output
34    // parameter. As input parameter it indicates the size of audioBuffer.
35    // As output parameter it indicates the number of bytes written to
36    // audioBuffer.
37    // Note: This API only play mono audio but can be used on file containing
38    // audio with more channels (in which case the audio will be converted to
39    // mono).
40    virtual int32_t PlayoutAudioData(
41        int8_t* audioBuffer,
42        uint32_t& dataLengthInBytes) = 0;
43
44    // Put one video frame into videoBuffer. dataLengthInBytes is both an input
45    // and output parameter. As input parameter it indicates the size of
46    // videoBuffer. As output parameter it indicates the number of bytes written
47    // to videoBuffer.
48    virtual int32_t PlayoutAVIVideoData(
49        int8_t* videoBuffer,
50        uint32_t& dataLengthInBytes) = 0;
51
52    // Put 10-60ms, depending on codec frame size, of audio data from file into
53    // audioBufferLeft and audioBufferRight. The buffers contain the left and
54    // right channel of played out stereo audio.
55    // dataLengthInBytes is both an input and output parameter. As input
56    // parameter it indicates the size of both audioBufferLeft and
57    // audioBufferRight. As output parameter it indicates the number of bytes
58    // written to both audio buffers.
59    // Note: This API can only be successfully called for WAV files with stereo
60    // audio.
61    virtual int32_t PlayoutStereoData(
62        int8_t* audioBufferLeft,
63        int8_t* audioBufferRight,
64        uint32_t& dataLengthInBytes) = 0;
65
66    // Open the file specified by fileName (relative path is allowed) for
67    // reading. FileCallback::PlayNotification(..) will be called after
68    // notificationTimeMs of the file has been played if notificationTimeMs is
69    // greater than zero. If loop is true the file will be played until
70    // StopPlaying() is called. When end of file is reached the file is read
71    // from the start. format specifies the type of file fileName refers to.
72    // codecInst specifies the encoding of the audio data. Note that
73    // file formats that contain this information (like WAV files) don't need to
74    // provide a non-NULL codecInst. startPointMs and stopPointMs, unless zero,
75    // specify what part of the file should be read. From startPointMs ms to
76    // stopPointMs ms.
77    // Note: codecInst.channels should be set to 2 for stereo (and 1 for
78    // mono). Stereo audio is only supported for WAV files.
79    virtual int32_t StartPlayingAudioFile(
80        const char* fileName,
81        const uint32_t notificationTimeMs = 0,
82        const bool loop                         = false,
83        const FileFormats format                = kFileFormatPcm16kHzFile,
84        const CodecInst* codecInst              = NULL,
85        const uint32_t startPointMs       = 0,
86        const uint32_t stopPointMs        = 0) = 0;
87
88    // Open the file specified by fileName for reading (relative path is
89    // allowed). If loop is true the file will be played until StopPlaying() is
90    // called. When end of file is reached the file is read from the start.
91    // format specifies the type of file fileName refers to. Only video will be
92    // read if videoOnly is true.
93    virtual int32_t StartPlayingVideoFile(const char* fileName,
94                                                const bool loop,
95                                                bool videoOnly,
96                                                const FileFormats format) = 0;
97
98    // Prepare for playing audio from stream.
99    // FileCallback::PlayNotification(..) will be called after
100    // notificationTimeMs of the file has been played if notificationTimeMs is
101    // greater than zero. format specifies the type of file fileName refers to.
102    // codecInst specifies the encoding of the audio data. Note that
103    // file formats that contain this information (like WAV files) don't need to
104    // provide a non-NULL codecInst. startPointMs and stopPointMs, unless zero,
105    // specify what part of the file should be read. From startPointMs ms to
106    // stopPointMs ms.
107    // Note: codecInst.channels should be set to 2 for stereo (and 1 for
108    // mono). Stereo audio is only supported for WAV files.
109    virtual int32_t StartPlayingAudioStream(
110        InStream& stream,
111        const uint32_t notificationTimeMs = 0,
112        const FileFormats    format             = kFileFormatPcm16kHzFile,
113        const CodecInst*     codecInst          = NULL,
114        const uint32_t startPointMs       = 0,
115        const uint32_t stopPointMs        = 0) = 0;
116
117    // Stop playing from file or stream.
118    virtual int32_t StopPlaying() = 0;
119
120    // Return true if playing.
121    virtual bool IsPlaying() = 0;
122
123
124    // Set durationMs to the number of ms that has been played from file.
125    virtual int32_t PlayoutPositionMs(
126        uint32_t& durationMs) const = 0;
127
128    // Write one audio frame, i.e. the bufferLength first bytes of audioBuffer,
129    // to file. The audio frame size is determined by the codecInst.pacsize
130    // parameter of the last sucessfull StartRecordingAudioFile(..) call.
131    // Note: bufferLength must be exactly one frame.
132    virtual int32_t IncomingAudioData(
133        const int8_t*  audioBuffer,
134        const uint32_t bufferLength) = 0;
135
136    // Write one video frame, i.e. the bufferLength first bytes of videoBuffer,
137    // to file.
138    // Note: videoBuffer can contain encoded data. The codec used must be the
139    // same as what was specified by videoCodecInst for the last successfull
140    // StartRecordingVideoFile(..) call. The videoBuffer must contain exactly
141    // one video frame.
142    virtual int32_t IncomingAVIVideoData(
143        const int8_t*  videoBuffer,
144        const uint32_t bufferLength) = 0;
145
146    // Open/creates file specified by fileName for writing (relative path is
147    // allowed). FileCallback::RecordNotification(..) will be called after
148    // notificationTimeMs of audio data has been recorded if
149    // notificationTimeMs is greater than zero.
150    // format specifies the type of file that should be created/opened.
151    // codecInst specifies the encoding of the audio data. maxSizeBytes
152    // specifies the number of bytes allowed to be written to file if it is
153    // greater than zero.
154    // Note: codecInst.channels should be set to 2 for stereo (and 1 for
155    // mono). Stereo is only supported for WAV files.
156    virtual int32_t StartRecordingAudioFile(
157        const char*  fileName,
158        const FileFormats    format,
159        const CodecInst&     codecInst,
160        const uint32_t notificationTimeMs = 0,
161        const uint32_t maxSizeBytes       = 0) = 0;
162
163    // Open/create the file specified by fileName for writing audio/video data
164    // (relative path is allowed). format specifies the type of file fileName
165    // should be. codecInst specifies the encoding of the audio data.
166    // videoCodecInst specifies the encoding of the video data. Only video data
167    // will be recorded if videoOnly is true.
168    virtual int32_t StartRecordingVideoFile(
169        const char* fileName,
170        const FileFormats   format,
171        const CodecInst&    codecInst,
172        const VideoCodec&   videoCodecInst,
173        bool videoOnly = false) = 0;
174
175    // Prepare for recording audio to stream.
176    // FileCallback::RecordNotification(..) will be called after
177    // notificationTimeMs of audio data has been recorded if
178    // notificationTimeMs is greater than zero.
179    // format specifies the type of file that stream should correspond to.
180    // codecInst specifies the encoding of the audio data.
181    // Note: codecInst.channels should be set to 2 for stereo (and 1 for
182    // mono). Stereo is only supported for WAV files.
183    virtual int32_t StartRecordingAudioStream(
184        OutStream&           stream,
185        const FileFormats    format,
186        const CodecInst&     codecInst,
187        const uint32_t notificationTimeMs = 0) = 0;
188
189    // Stop recording to file or stream.
190    virtual int32_t StopRecording() = 0;
191
192    // Return true if recording.
193    virtual bool IsRecording() = 0;
194
195    // Set durationMs to the number of ms that has been recorded to file.
196    virtual int32_t RecordDurationMs(uint32_t& durationMs) = 0;
197
198    // Return true if recording or playing is stereo.
199    virtual bool IsStereo() = 0;
200
201    // Register callback to receive media file related notifications. Disables
202    // callbacks if callback is NULL.
203    virtual int32_t SetModuleFileCallback(FileCallback* callback) = 0;
204
205    // Set durationMs to the size of the file (in ms) specified by fileName.
206    // format specifies the type of file fileName refers to. freqInHz specifies
207    // the sampling frequency of the file.
208    virtual int32_t FileDurationMs(
209        const char*  fileName,
210        uint32_t&      durationMs,
211        const FileFormats    format,
212        const uint32_t freqInHz = 16000) = 0;
213
214    // Update codecInst according to the current audio codec being used for
215    // reading or writing.
216    virtual int32_t codec_info(CodecInst& codecInst) const = 0;
217
218    // Update videoCodecInst according to the current video codec being used for
219    // reading or writing.
220    virtual int32_t VideoCodecInst(VideoCodec& videoCodecInst) const = 0;
221
222protected:
223    MediaFile() {}
224    virtual ~MediaFile() {}
225};
226}  // namespace webrtc
227#endif // WEBRTC_MODULES_MEDIA_FILE_INTERFACE_MEDIA_FILE_H_
228