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// This sub-API supports the following functionalities:
12//
13//  - File playback.
14//  - File recording.
15//  - File conversion.
16//
17// Usage example, omitting error checking:
18//
19//  using namespace webrtc;
20//  VoiceEngine* voe = VoiceEngine::Create();
21//  VoEBase* base = VoEBase::GetInterface(voe);
22//  VoEFile* file  = VoEFile::GetInterface(voe);
23//  base->Init();
24//  int ch = base->CreateChannel();
25//  ...
26//  base->StartPlayout(ch);
27//  file->StartPlayingFileAsMicrophone(ch, "data_file_16kHz.pcm", true);
28//  ...
29//  file->StopPlayingFileAsMicrophone(ch);
30//  base->StopPlayout(ch);
31//  ...
32//  base->DeleteChannel(ch);
33//  base->Terminate();
34//  base->Release();
35//  file->Release();
36//  VoiceEngine::Delete(voe);
37//
38#ifndef WEBRTC_VOICE_ENGINE_VOE_FILE_H
39#define WEBRTC_VOICE_ENGINE_VOE_FILE_H
40
41#include "webrtc/common_types.h"
42
43namespace webrtc {
44
45class VoiceEngine;
46
47class WEBRTC_DLLEXPORT VoEFile
48{
49public:
50    // Factory for the VoEFile sub-API. Increases an internal
51    // reference counter if successful. Returns NULL if the API is not
52    // supported or if construction fails.
53    static VoEFile* GetInterface(VoiceEngine* voiceEngine);
54
55    // Releases the VoEFile sub-API and decreases an internal
56    // reference counter. Returns the new reference count. This value should
57    // be zero for all sub-API:s before the VoiceEngine object can be safely
58    // deleted.
59    virtual int Release() = 0;
60
61    // Starts playing and mixing files with the local speaker signal for
62    // playout.
63    virtual int StartPlayingFileLocally(
64        int channel,
65        const char fileNameUTF8[1024],
66        bool loop = false,
67        FileFormats format = kFileFormatPcm16kHzFile,
68        float volumeScaling = 1.0,
69        int startPointMs = 0,
70        int stopPointMs = 0) = 0;
71
72    // Starts playing and mixing streams with the local speaker signal for
73    // playout.
74    virtual int StartPlayingFileLocally(
75        int channel,
76        InStream* stream,
77        FileFormats format = kFileFormatPcm16kHzFile,
78        float volumeScaling = 1.0,
79        int startPointMs = 0, int stopPointMs = 0) = 0;
80
81    // Stops playback of a file on a specific |channel|.
82    virtual int StopPlayingFileLocally(int channel) = 0;
83
84    // Returns the current file playing state for a specific |channel|.
85    virtual int IsPlayingFileLocally(int channel) = 0;
86
87    // Starts reading data from a file and transmits the data either
88    // mixed with or instead of the microphone signal.
89    virtual int StartPlayingFileAsMicrophone(
90        int channel,
91        const char fileNameUTF8[1024],
92        bool loop = false ,
93        bool mixWithMicrophone = false,
94        FileFormats format = kFileFormatPcm16kHzFile,
95        float volumeScaling = 1.0) = 0;
96
97    // Starts reading data from a stream and transmits the data either
98    // mixed with or instead of the microphone signal.
99    virtual int StartPlayingFileAsMicrophone(
100        int channel,
101        InStream* stream,
102        bool mixWithMicrophone = false,
103        FileFormats format = kFileFormatPcm16kHzFile,
104        float volumeScaling = 1.0) = 0;
105
106    // Stops playing of a file as microphone signal for a specific |channel|.
107    virtual int StopPlayingFileAsMicrophone(int channel) = 0;
108
109    // Returns whether the |channel| is currently playing a file as microphone.
110    virtual int IsPlayingFileAsMicrophone(int channel) = 0;
111
112    // Starts recording the mixed playout audio.
113    virtual int StartRecordingPlayout(int channel,
114                                      const char* fileNameUTF8,
115                                      CodecInst* compression = NULL,
116                                      int maxSizeBytes = -1) = 0;
117
118    // Stops recording the mixed playout audio.
119    virtual int StopRecordingPlayout(int channel) = 0;
120
121    virtual int StartRecordingPlayout(int channel,
122                                      OutStream* stream,
123                                      CodecInst* compression = NULL) = 0;
124
125    // Starts recording the microphone signal to a file.
126    virtual int StartRecordingMicrophone(const char* fileNameUTF8,
127                                         CodecInst* compression = NULL,
128                                         int maxSizeBytes = -1) = 0;
129
130    // Starts recording the microphone signal to a stream.
131    virtual int StartRecordingMicrophone(OutStream* stream,
132                                         CodecInst* compression = NULL) = 0;
133
134    // Stops recording the microphone signal.
135    virtual int StopRecordingMicrophone() = 0;
136
137    // Don't use. To be removed.
138    virtual int ScaleLocalFilePlayout(int channel, float scale) { return -1; }
139    virtual int ScaleFileAsMicrophonePlayout(
140            int channel, float scale) { return -1; }
141    virtual int GetFileDuration(const char* fileNameUTF8, int& durationMs,
142            FileFormats format = kFileFormatPcm16kHzFile) { return -1; }
143    virtual int GetPlaybackPosition(int channel, int& positionMs) { return -1; }
144    virtual int ConvertPCMToWAV(const char* fileNameInUTF8,
145                                const char* fileNameOutUTF8) { return -1; }
146    virtual int ConvertPCMToWAV(InStream* streamIn,
147                                OutStream* streamOut) { return -1; }
148    virtual int ConvertWAVToPCM(const char* fileNameInUTF8,
149                                const char* fileNameOutUTF8) { return -1; }
150    virtual int ConvertWAVToPCM(InStream* streamIn,
151                                OutStream* streamOut) { return -1; }
152    virtual int ConvertPCMToCompressed(const char* fileNameInUTF8,
153                                       const char* fileNameOutUTF8,
154                                       CodecInst* compression) { return -1; }
155    virtual int ConvertPCMToCompressed(InStream* streamIn,
156                                       OutStream* streamOut,
157                                       CodecInst* compression) { return -1; }
158    virtual int ConvertCompressedToPCM(const char* fileNameInUTF8,
159            const char* fileNameOutUTF8) { return -1; }
160    virtual int ConvertCompressedToPCM(InStream* streamIn,
161                                       OutStream* streamOut) { return -1; }
162protected:
163    VoEFile() {}
164    virtual ~VoEFile() {}
165};
166
167}  // namespace webrtc
168
169#endif  // WEBRTC_VOICE_ENGINE_VOE_FILE_H
170