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 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: 176 MediaFile() {} 177 virtual ~MediaFile() {} 178 }; 179 } // namespace webrtc 180 #endif // WEBRTC_MODULES_MEDIA_FILE_INTERFACE_MEDIA_FILE_H_ 181