1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
2 /*
3     bqaudioio
4 
5     Copyright 2007-2016 Particular Programs Ltd.
6 
7     Permission is hereby granted, free of charge, to any person
8     obtaining a copy of this software and associated documentation
9     files (the "Software"), to deal in the Software without
10     restriction, including without limitation the rights to use, copy,
11     modify, merge, publish, distribute, sublicense, and/or sell copies
12     of the Software, and to permit persons to whom the Software is
13     furnished to do so, subject to the following conditions:
14 
15     The above copyright notice and this permission notice shall be
16     included in all copies or substantial portions of the Software.
17 
18     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
21     NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
22     ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
23     CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
24     WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25 
26     Except as contained in this notice, the names of Chris Cannam and
27     Particular Programs Ltd shall not be used in advertising or
28     otherwise to promote the sale, use or other dealings in this
29     Software without prior written authorization.
30 */
31 
32 #ifndef BQAUDIOIO_APPLICATION_RECORD_TARGET_H
33 #define BQAUDIOIO_APPLICATION_RECORD_TARGET_H
34 
35 #include <string>
36 
37 namespace breakfastquay {
38 
39 class SystemRecordSource;
40 
41 /**
42  * Interface for an application sink that accepts recorded samples. To
43  * be implemented in the application and passed to
44  * AudioFactory::createCallbackRecordSource or createAudioIO.
45  */
46 class ApplicationRecordTarget
47 {
48 public:
~ApplicationRecordTarget()49     virtual ~ApplicationRecordTarget() { }
50 
51     /**
52      * Return an identifier for the application client. May be used in
53      * connection strings or (possibly) error and logging information.
54      */
55     virtual std::string getClientName() const = 0;
56 
57     /**
58      * Return the sample rate at which the application runs. The
59      * source or IO will attempt to open its device at the rate
60      * returned by this call at the point where the device is opened,
61      * although it might not succeed; it will provide the actual rate
62      * through a subsequent call to setSystemPlaybackSampleRate.
63      *
64      * Return 0 if the application has no central sample rate of its
65      * own and is happy to accept the default rate of the device.
66      */
getApplicationSampleRate()67     virtual int getApplicationSampleRate() const { return 0; }
68 
69     /**
70      * Return the number of audio channels expected by the
71      * application. The source or IO will attempt to open its device
72      * with this number of channels, though it might not succeed; it
73      * will provide the actual number of channels through a subsequent
74      * call to setSystemPlaybackChannelCount and will mixdown as
75      * appropriate.
76      *
77      * This must not be zero and is not expected to change during the
78      * lifetime of the source or IO.
79     */
80     virtual int getApplicationChannelCount() const = 0;
81 
82     /**
83      * Called by the system source/IO if processing will be using a
84      * fixed block size, to tell the application what that block size
85      * will be (in sample frames). If this is not called, the
86      * application must assume that any number of samples could be
87      * provided at a time.
88      */
89     virtual void setSystemRecordBlockSize(int) = 0;
90 
91     /**
92      * Called by the system source/IO to tell the application the
93      * sample rate at which the audio device was opened.
94      */
95     virtual void setSystemRecordSampleRate(int) = 0;
96 
97     /**
98      * Called by the system source/IO to tell the application the
99      * actual number of channels with which the audio device was
100      * opened. Note that the source/IO handles channel mapping and
101      * mixdown; this is just informative.
102      */
103     virtual void setSystemRecordChannelCount(int) = 0;
104 
105     /**
106      * Called by the system source/IO to tell the application the
107      * system record latency in sample frames.
108      */
109     virtual void setSystemRecordLatency(int) = 0;
110 
111     /**
112      * Accept a number of audio sample frames that have been received
113      * from the record device. The samples pointer will point to
114      * nchannels channel buffers each having nframes samples. The
115      * value of nchannels will be whatever
116      * getApplicationChannelCount() returned at the time the device
117      * was initialised.
118      *
119      * This may be called from realtime context.
120      */
121     virtual void putSamples(const float *const *samples, int nchannels, int nframes) = 0;
122 
123     /**
124      * Report peak input levels for the last output
125      * buffer. Potentially useful for monitoring.
126      *
127      * This may be called from realtime context.
128      */
129     virtual void setInputLevels(float peakLeft, float peakRight) = 0;
130 
131     /**
132      * Called when an audio dropout is reported due to a processing
133      * overload.
134      */
audioProcessingOverload()135     virtual void audioProcessingOverload() { }
136 };
137 
138 }
139 #endif
140 
141