• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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_MEDIA_FILE_H_
12 #define WEBRTC_MODULES_MEDIA_FILE_MEDIA_FILE_H_
13 
14 #include "webrtc/common_types.h"
15 #include "webrtc/modules/include/module.h"
16 #include "webrtc/modules/include/module_common_types.h"
17 #include "webrtc/modules/media_file/media_file_defines.h"
18 #include "webrtc/typedefs.h"
19 
20 namespace webrtc {
21 class MediaFile : public Module
22 {
23 public:
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     // Put 10-60ms of audio data from file into the audioBuffer depending on
30     // codec frame size. dataLengthInBytes is both an input and output
31     // parameter. As input parameter it indicates the size of audioBuffer.
32     // As output parameter it indicates the number of bytes written to
33     // audioBuffer.
34     // Note: This API only play mono audio but can be used on file containing
35     // audio with more channels (in which case the audio will be converted to
36     // mono).
37     virtual int32_t PlayoutAudioData(
38         int8_t* audioBuffer,
39         size_t& dataLengthInBytes) = 0;
40 
41     // Put 10-60ms, depending on codec frame size, of audio data from file into
42     // audioBufferLeft and audioBufferRight. The buffers contain the left and
43     // right channel of played out stereo audio.
44     // dataLengthInBytes is both an input and output parameter. As input
45     // parameter it indicates the size of both audioBufferLeft and
46     // audioBufferRight. As output parameter it indicates the number of bytes
47     // written to both audio buffers.
48     // Note: This API can only be successfully called for WAV files with stereo
49     // audio.
50     virtual int32_t PlayoutStereoData(
51         int8_t* audioBufferLeft,
52         int8_t* audioBufferRight,
53         size_t& dataLengthInBytes) = 0;
54 
55     // Open the file specified by fileName (relative path is allowed) for
56     // reading. FileCallback::PlayNotification(..) will be called after
57     // notificationTimeMs of the file has been played if notificationTimeMs is
58     // greater than zero. If loop is true the file will be played until
59     // StopPlaying() is called. When end of file is reached the file is read
60     // from the start. format specifies the type of file fileName refers to.
61     // codecInst specifies the encoding of the audio data. Note that
62     // file formats that contain this information (like WAV files) don't need to
63     // provide a non-NULL codecInst. startPointMs and stopPointMs, unless zero,
64     // specify what part of the file should be read. From startPointMs ms to
65     // stopPointMs ms.
66     // Note: codecInst.channels should be set to 2 for stereo (and 1 for
67     // mono). Stereo audio is only supported for WAV files.
68     virtual int32_t StartPlayingAudioFile(
69         const char* fileName,
70         const uint32_t notificationTimeMs = 0,
71         const bool loop                         = false,
72         const FileFormats format                = kFileFormatPcm16kHzFile,
73         const CodecInst* codecInst              = NULL,
74         const uint32_t startPointMs       = 0,
75         const uint32_t stopPointMs        = 0) = 0;
76 
77     // Prepare for playing audio from stream.
78     // FileCallback::PlayNotification(..) will be called after
79     // notificationTimeMs of the file has been played if notificationTimeMs is
80     // greater than zero. format specifies the type of file fileName refers to.
81     // codecInst specifies the encoding of the audio data. Note that
82     // file formats that contain this information (like WAV files) don't need to
83     // provide a non-NULL codecInst. startPointMs and stopPointMs, unless zero,
84     // specify what part of the file should be read. From startPointMs ms to
85     // stopPointMs ms.
86     // Note: codecInst.channels should be set to 2 for stereo (and 1 for
87     // mono). Stereo audio is only supported for WAV files.
88     virtual int32_t StartPlayingAudioStream(
89         InStream& stream,
90         const uint32_t notificationTimeMs = 0,
91         const FileFormats    format             = kFileFormatPcm16kHzFile,
92         const CodecInst*     codecInst          = NULL,
93         const uint32_t startPointMs       = 0,
94         const uint32_t stopPointMs        = 0) = 0;
95 
96     // Stop playing from file or stream.
97     virtual int32_t StopPlaying() = 0;
98 
99     // Return true if playing.
100     virtual bool IsPlaying() = 0;
101 
102 
103     // Set durationMs to the number of ms that has been played from file.
104     virtual int32_t PlayoutPositionMs(
105         uint32_t& durationMs) const = 0;
106 
107     // Write one audio frame, i.e. the bufferLength first bytes of audioBuffer,
108     // to file. The audio frame size is determined by the codecInst.pacsize
109     // parameter of the last sucessfull StartRecordingAudioFile(..) call.
110     // Note: bufferLength must be exactly one frame.
111     virtual int32_t IncomingAudioData(
112         const int8_t* audioBuffer,
113         const size_t bufferLength) = 0;
114 
115     // Open/creates file specified by fileName for writing (relative path is
116     // allowed). FileCallback::RecordNotification(..) will be called after
117     // notificationTimeMs of audio data has been recorded if
118     // notificationTimeMs is greater than zero.
119     // format specifies the type of file that should be created/opened.
120     // codecInst specifies the encoding of the audio data. maxSizeBytes
121     // specifies the number of bytes allowed to be written to file if it is
122     // greater than zero.
123     // Note: codecInst.channels should be set to 2 for stereo (and 1 for
124     // mono). Stereo is only supported for WAV files.
125     virtual int32_t StartRecordingAudioFile(
126         const char*  fileName,
127         const FileFormats    format,
128         const CodecInst&     codecInst,
129         const uint32_t notificationTimeMs = 0,
130         const uint32_t maxSizeBytes       = 0) = 0;
131 
132     // Prepare for recording audio to stream.
133     // FileCallback::RecordNotification(..) will be called after
134     // notificationTimeMs of audio data has been recorded if
135     // notificationTimeMs is greater than zero.
136     // format specifies the type of file that stream should correspond to.
137     // codecInst specifies the encoding of the audio data.
138     // Note: codecInst.channels should be set to 2 for stereo (and 1 for
139     // mono). Stereo is only supported for WAV files.
140     virtual int32_t StartRecordingAudioStream(
141         OutStream&           stream,
142         const FileFormats    format,
143         const CodecInst&     codecInst,
144         const uint32_t notificationTimeMs = 0) = 0;
145 
146     // Stop recording to file or stream.
147     virtual int32_t StopRecording() = 0;
148 
149     // Return true if recording.
150     virtual bool IsRecording() = 0;
151 
152     // Set durationMs to the number of ms that has been recorded to file.
153     virtual int32_t RecordDurationMs(uint32_t& durationMs) = 0;
154 
155     // Return true if recording or playing is stereo.
156     virtual bool IsStereo() = 0;
157 
158     // Register callback to receive media file related notifications. Disables
159     // callbacks if callback is NULL.
160     virtual int32_t SetModuleFileCallback(FileCallback* callback) = 0;
161 
162     // Set durationMs to the size of the file (in ms) specified by fileName.
163     // format specifies the type of file fileName refers to. freqInHz specifies
164     // the sampling frequency of the file.
165     virtual int32_t FileDurationMs(
166         const char*  fileName,
167         uint32_t&      durationMs,
168         const FileFormats    format,
169         const uint32_t freqInHz = 16000) = 0;
170 
171     // Update codecInst according to the current audio codec being used for
172     // reading or writing.
173     virtual int32_t codec_info(CodecInst& codecInst) const = 0;
174 
175 protected:
MediaFile()176     MediaFile() {}
~MediaFile()177     virtual ~MediaFile() {}
178 };
179 }  // namespace webrtc
180 #endif // WEBRTC_MODULES_MEDIA_FILE_MEDIA_FILE_H_
181