media/webrtc/trunk/src/voice_engine/include/voe_external_media.h

   1 /*
   2  *  Copyright (c) 2011 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 // In some cases it is desirable to use an audio source or sink which may
  12 // not be available to the VoiceEngine, such as a DV camera. This sub-API
  13 // contains functions that allow for the use of such external recording
  14 // sources and playout sinks. It also describes how recorded data, or data
  15 // to be played out, can be modified outside the VoiceEngine.
  16 //
  17 // Usage example, omitting error checking:
  18 //
  19 //  using namespace webrtc;
  20 //  VoiceEngine* voe = VoiceEngine::Create();
  21 //  VoEBase* base = VoEBase::GetInterface(voe);
  22 //  VoEMediaProcess media = VoEMediaProcess::GetInterface(voe);
  23 //  base->Init();
  24 //  ...
  25 //  media->SetExternalRecordingStatus(true);
  26 //  ...
  27 //  base->Terminate();
  28 //  base->Release();
  29 //  media->Release();
  30 //  VoiceEngine::Delete(voe);
  31 //
  32 #ifndef WEBRTC_VOICE_ENGINE_VOE_EXTERNAL_MEDIA_H
  33 #define WEBRTC_VOICE_ENGINE_VOE_EXTERNAL_MEDIA_H
  34
  35 #include "common_types.h"
  36
  37 namespace webrtc {
  38
  39 class VoiceEngine;
  40
  41 class WEBRTC_DLLEXPORT VoEMediaProcess
  42 {
  43 public:
  44     // The VoiceEngine user should override the Process() method in a
  45     // derived class. Process() will be called when audio is ready to
  46     // be processed. The audio can be accessed in several different modes
  47     // given by the |type| parameter. The function should modify the
  48     // original data and ensure that it is copied back to the |audio10ms|
  49     // array. The number of samples in the frame cannot be changed.
  50     // The sampling frequency will depend upon the codec used.
  51     // If |isStereo| is true, audio10ms will contain 16-bit PCM data
  52     // samples in interleaved stereo format (L0,R0,L1,R1,…):
  53     virtual void Process(const int channel, const ProcessingTypes type,
  54                          WebRtc_Word16 audio10ms[], const int length,
  55                          const int samplingFreq, const bool isStereo) = 0;
  56
  57 protected:
  58     virtual ~VoEMediaProcess() {}
  59 };
  60
  61 class WEBRTC_DLLEXPORT VoEExternalMedia
  62 {
  63 public:
  64     // Factory for the VoEExternalMedia sub-API. Increases an internal
  65     // reference counter if successful. Returns NULL if the API is not
  66     // supported or if construction fails.
  67     static VoEExternalMedia* GetInterface(VoiceEngine* voiceEngine);
  68
  69     // Releases the VoEExternalMedia sub-API and decreases an internal
  70     // reference counter. Returns the new reference count. This value should
  71     // be zero for all sub-API:s before the VoiceEngine object can be safely
  72     // deleted.
  73     virtual int Release() = 0;
  74
  75     // Installs a VoEMediaProcess derived instance and activates external
  76     // media for the specified |channel| and |type|.
  77     virtual int RegisterExternalMediaProcessing(
  78         int channel, ProcessingTypes type, VoEMediaProcess& processObject) = 0;
  79
  80     // Removes the VoEMediaProcess derived instance and deactivates external
  81     // media for the specified |channel| and |type|.
  82     virtual int DeRegisterExternalMediaProcessing(
  83         int channel, ProcessingTypes type) = 0;
  84
  85     // Toogles state of external recording.
  86     virtual int SetExternalRecordingStatus(bool enable) = 0;
  87
  88     // Toogles state of external playout.
  89     virtual int SetExternalPlayoutStatus(bool enable) = 0;
  90
  91     // This function accepts externally recorded audio. During transmission,
  92     // this method should be called at as regular an interval as possible
  93     // with frames of corresponding size.
  94     virtual int ExternalRecordingInsertData(
  95         const WebRtc_Word16 speechData10ms[], int lengthSamples,
  96         int samplingFreqHz, int current_delay_ms) = 0;
  97
  98     // This function gets audio for an external playout sink.
  99     // During transmission, this function should be called every ~10 ms
 100     // to obtain a new 10 ms frame of audio. The length of the block will
 101     // be 160, 320, 440 or 480 samples (for 16, 32, 44 or 48 kHz sampling
 102     // rates respectively).
 103     virtual int ExternalPlayoutGetData(
 104         WebRtc_Word16 speechData10ms[], int samplingFreqHz,
 105         int current_delay_ms, int& lengthSamples) = 0;
 106
 107 protected:
 108     VoEExternalMedia() {}
 109     virtual ~VoEExternalMedia() {}
 110 };
 111
 112 }  // namespace webrtc
 113
 114 #endif  //  WEBRTC_VOICE_ENGINE_VOE_EXTERNAL_MEDIA_H