src/third_party/webrtc/modules/media_file/interface/media_file.h

   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     // 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
 222 protected:
 223     MediaFile() {}
 224     virtual ~MediaFile() {}
 225 };
 226 }  // namespace webrtc
 227 #endif // WEBRTC_MODULES_MEDIA_FILE_INTERFACE_MEDIA_FILE_H_