EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2026-06-02 08:58:13
0001 //////////////////////////////////////////////////////////// 0002 // 0003 // SFML - Simple and Fast Multimedia Library 0004 // Copyright (C) 2007-2023 Laurent Gomila (laurent@sfml-dev.org) 0005 // 0006 // This software is provided 'as-is', without any express or implied warranty. 0007 // In no event will the authors be held liable for any damages arising from the use of this software. 0008 // 0009 // Permission is granted to anyone to use this software for any purpose, 0010 // including commercial applications, and to alter it and redistribute it freely, 0011 // subject to the following restrictions: 0012 // 0013 // 1. The origin of this software must not be misrepresented; 0014 // you must not claim that you wrote the original software. 0015 // If you use this software in a product, an acknowledgment 0016 // in the product documentation would be appreciated but is not required. 0017 // 0018 // 2. Altered source versions must be plainly marked as such, 0019 // and must not be misrepresented as being the original software. 0020 // 0021 // 3. This notice may not be removed or altered from any source distribution. 0022 // 0023 //////////////////////////////////////////////////////////// 0024 0025 #ifndef SFML_SOUNDRECORDER_HPP 0026 #define SFML_SOUNDRECORDER_HPP 0027 0028 //////////////////////////////////////////////////////////// 0029 // Headers 0030 //////////////////////////////////////////////////////////// 0031 #include <SFML/Audio/Export.hpp> 0032 #include <SFML/Audio/AlResource.hpp> 0033 #include <SFML/System/Thread.hpp> 0034 #include <SFML/System/Time.hpp> 0035 #include <vector> 0036 #include <string> 0037 0038 0039 namespace sf 0040 { 0041 //////////////////////////////////////////////////////////// 0042 /// \brief Abstract base class for capturing sound data 0043 /// 0044 //////////////////////////////////////////////////////////// 0045 class SFML_AUDIO_API SoundRecorder : AlResource 0046 { 0047 public: 0048 0049 //////////////////////////////////////////////////////////// 0050 /// \brief destructor 0051 /// 0052 //////////////////////////////////////////////////////////// 0053 virtual ~SoundRecorder(); 0054 0055 //////////////////////////////////////////////////////////// 0056 /// \brief Start the capture 0057 /// 0058 /// The \a sampleRate parameter defines the number of audio samples 0059 /// captured per second. The higher, the better the quality 0060 /// (for example, 44100 samples/sec is CD quality). 0061 /// This function uses its own thread so that it doesn't block 0062 /// the rest of the program while the capture runs. 0063 /// Please note that only one capture can happen at the same time. 0064 /// You can select which capture device will be used, by passing 0065 /// the name to the setDevice() method. If none was selected 0066 /// before, the default capture device will be used. You can get a 0067 /// list of the names of all available capture devices by calling 0068 /// getAvailableDevices(). 0069 /// 0070 /// \param sampleRate Desired capture rate, in number of samples per second 0071 /// 0072 /// \return True, if start of capture was successful 0073 /// 0074 /// \see stop, getAvailableDevices 0075 /// 0076 //////////////////////////////////////////////////////////// 0077 bool start(unsigned int sampleRate = 44100); 0078 0079 //////////////////////////////////////////////////////////// 0080 /// \brief Stop the capture 0081 /// 0082 /// \see start 0083 /// 0084 //////////////////////////////////////////////////////////// 0085 void stop(); 0086 0087 //////////////////////////////////////////////////////////// 0088 /// \brief Get the sample rate 0089 /// 0090 /// The sample rate defines the number of audio samples 0091 /// captured per second. The higher, the better the quality 0092 /// (for example, 44100 samples/sec is CD quality). 0093 /// 0094 /// \return Sample rate, in samples per second 0095 /// 0096 //////////////////////////////////////////////////////////// 0097 unsigned int getSampleRate() const; 0098 0099 //////////////////////////////////////////////////////////// 0100 /// \brief Get a list of the names of all available audio capture devices 0101 /// 0102 /// This function returns a vector of strings, containing 0103 /// the names of all available audio capture devices. 0104 /// 0105 /// \return A vector of strings containing the names 0106 /// 0107 //////////////////////////////////////////////////////////// 0108 static std::vector<std::string> getAvailableDevices(); 0109 0110 //////////////////////////////////////////////////////////// 0111 /// \brief Get the name of the default audio capture device 0112 /// 0113 /// This function returns the name of the default audio 0114 /// capture device. If none is available, an empty string 0115 /// is returned. 0116 /// 0117 /// \return The name of the default audio capture device 0118 /// 0119 //////////////////////////////////////////////////////////// 0120 static std::string getDefaultDevice(); 0121 0122 //////////////////////////////////////////////////////////// 0123 /// \brief Set the audio capture device 0124 /// 0125 /// This function sets the audio capture device to the device 0126 /// with the given \a name. It can be called on the fly (i.e: 0127 /// while recording). If you do so while recording and 0128 /// opening the device fails, it stops the recording. 0129 /// 0130 /// \param name The name of the audio capture device 0131 /// 0132 /// \return True, if it was able to set the requested device 0133 /// 0134 /// \see getAvailableDevices, getDefaultDevice 0135 /// 0136 //////////////////////////////////////////////////////////// 0137 bool setDevice(const std::string& name); 0138 0139 //////////////////////////////////////////////////////////// 0140 /// \brief Get the name of the current audio capture device 0141 /// 0142 /// \return The name of the current audio capture device 0143 /// 0144 //////////////////////////////////////////////////////////// 0145 const std::string& getDevice() const; 0146 0147 //////////////////////////////////////////////////////////// 0148 /// \brief Set the channel count of the audio capture device 0149 /// 0150 /// This method allows you to specify the number of channels 0151 /// used for recording. Currently only 16-bit mono and 0152 /// 16-bit stereo are supported. 0153 /// 0154 /// \param channelCount Number of channels. Currently only 0155 /// mono (1) and stereo (2) are supported. 0156 /// 0157 /// \see getChannelCount 0158 /// 0159 //////////////////////////////////////////////////////////// 0160 void setChannelCount(unsigned int channelCount); 0161 0162 //////////////////////////////////////////////////////////// 0163 /// \brief Get the number of channels used by this recorder 0164 /// 0165 /// Currently only mono and stereo are supported, so the 0166 /// value is either 1 (for mono) or 2 (for stereo). 0167 /// 0168 /// \return Number of channels 0169 /// 0170 /// \see setChannelCount 0171 /// 0172 //////////////////////////////////////////////////////////// 0173 unsigned int getChannelCount() const; 0174 0175 //////////////////////////////////////////////////////////// 0176 /// \brief Check if the system supports audio capture 0177 /// 0178 /// This function should always be called before using 0179 /// the audio capture features. If it returns false, then 0180 /// any attempt to use sf::SoundRecorder or one of its derived 0181 /// classes will fail. 0182 /// 0183 /// \return True if audio capture is supported, false otherwise 0184 /// 0185 //////////////////////////////////////////////////////////// 0186 static bool isAvailable(); 0187 0188 protected: 0189 0190 //////////////////////////////////////////////////////////// 0191 /// \brief Default constructor 0192 /// 0193 /// This constructor is only meant to be called by derived classes. 0194 /// 0195 //////////////////////////////////////////////////////////// 0196 SoundRecorder(); 0197 0198 //////////////////////////////////////////////////////////// 0199 /// \brief Set the processing interval 0200 /// 0201 /// The processing interval controls the period 0202 /// between calls to the onProcessSamples function. You may 0203 /// want to use a small interval if you want to process the 0204 /// recorded data in real time, for example. 0205 /// 0206 /// Note: this is only a hint, the actual period may vary. 0207 /// So don't rely on this parameter to implement precise timing. 0208 /// 0209 /// The default processing interval is 100 ms. 0210 /// 0211 /// \param interval Processing interval 0212 /// 0213 //////////////////////////////////////////////////////////// 0214 void setProcessingInterval(Time interval); 0215 0216 //////////////////////////////////////////////////////////// 0217 /// \brief Start capturing audio data 0218 /// 0219 /// This virtual function may be overridden by a derived class 0220 /// if something has to be done every time a new capture 0221 /// starts. If not, this function can be ignored; the default 0222 /// implementation does nothing. 0223 /// 0224 /// \return True to start the capture, or false to abort it 0225 /// 0226 //////////////////////////////////////////////////////////// 0227 virtual bool onStart(); 0228 0229 //////////////////////////////////////////////////////////// 0230 /// \brief Process a new chunk of recorded samples 0231 /// 0232 /// This virtual function is called every time a new chunk of 0233 /// recorded data is available. The derived class can then do 0234 /// whatever it wants with it (storing it, playing it, sending 0235 /// it over the network, etc.). 0236 /// 0237 /// \param samples Pointer to the new chunk of recorded samples 0238 /// \param sampleCount Number of samples pointed by \a samples 0239 /// 0240 /// \return True to continue the capture, or false to stop it 0241 /// 0242 //////////////////////////////////////////////////////////// 0243 virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount) = 0; 0244 0245 //////////////////////////////////////////////////////////// 0246 /// \brief Stop capturing audio data 0247 /// 0248 /// This virtual function may be overridden by a derived class 0249 /// if something has to be done every time the capture 0250 /// ends. If not, this function can be ignored; the default 0251 /// implementation does nothing. 0252 /// 0253 //////////////////////////////////////////////////////////// 0254 virtual void onStop(); 0255 0256 private: 0257 0258 //////////////////////////////////////////////////////////// 0259 /// \brief Function called as the entry point of the thread 0260 /// 0261 /// This function starts the recording loop, and returns 0262 /// only when the capture is stopped. 0263 /// 0264 //////////////////////////////////////////////////////////// 0265 void record(); 0266 0267 //////////////////////////////////////////////////////////// 0268 /// \brief Get the new available audio samples and process them 0269 /// 0270 /// This function is called continuously during the 0271 /// capture loop. It retrieves the captured samples and 0272 /// forwards them to the derived class. 0273 /// 0274 //////////////////////////////////////////////////////////// 0275 void processCapturedSamples(); 0276 0277 //////////////////////////////////////////////////////////// 0278 /// \brief Clean up the recorder's internal resources 0279 /// 0280 /// This function is called when the capture stops. 0281 /// 0282 //////////////////////////////////////////////////////////// 0283 void cleanup(); 0284 0285 //////////////////////////////////////////////////////////// 0286 // Member data 0287 //////////////////////////////////////////////////////////// 0288 Thread m_thread; //!< Thread running the background recording task 0289 std::vector<Int16> m_samples; //!< Buffer to store captured samples 0290 unsigned int m_sampleRate; //!< Sample rate 0291 Time m_processingInterval; //!< Time period between calls to onProcessSamples 0292 bool m_isCapturing; //!< Capturing state 0293 std::string m_deviceName; //!< Name of the audio capture device 0294 unsigned int m_channelCount; //!< Number of recording channels 0295 }; 0296 0297 } // namespace sf 0298 0299 0300 #endif // SFML_SOUNDRECORDER_HPP 0301 0302 0303 //////////////////////////////////////////////////////////// 0304 /// \class sf::SoundRecorder 0305 /// \ingroup audio 0306 /// 0307 /// sf::SoundBuffer provides a simple interface to access 0308 /// the audio recording capabilities of the computer 0309 /// (the microphone). As an abstract base class, it only cares 0310 /// about capturing sound samples, the task of making something 0311 /// useful with them is left to the derived class. Note that 0312 /// SFML provides a built-in specialization for saving the 0313 /// captured data to a sound buffer (see sf::SoundBufferRecorder). 0314 /// 0315 /// A derived class has only one virtual function to override: 0316 /// \li onProcessSamples provides the new chunks of audio samples while the capture happens 0317 /// 0318 /// Moreover, two additional virtual functions can be overridden 0319 /// as well if necessary: 0320 /// \li onStart is called before the capture happens, to perform custom initializations 0321 /// \li onStop is called after the capture ends, to perform custom cleanup 0322 /// 0323 /// A derived class can also control the frequency of the onProcessSamples 0324 /// calls, with the setProcessingInterval protected function. The default 0325 /// interval is chosen so that recording thread doesn't consume too much 0326 /// CPU, but it can be changed to a smaller value if you need to process 0327 /// the recorded data in real time, for example. 0328 /// 0329 /// The audio capture feature may not be supported or activated 0330 /// on every platform, thus it is recommended to check its 0331 /// availability with the isAvailable() function. If it returns 0332 /// false, then any attempt to use an audio recorder will fail. 0333 /// 0334 /// If you have multiple sound input devices connected to your 0335 /// computer (for example: microphone, external soundcard, webcam mic, ...) 0336 /// you can get a list of all available devices through the 0337 /// getAvailableDevices() function. You can then select a device 0338 /// by calling setDevice() with the appropriate device. Otherwise 0339 /// the default capturing device will be used. 0340 /// 0341 /// By default the recording is in 16-bit mono. Using the 0342 /// setChannelCount method you can change the number of channels 0343 /// used by the audio capture device to record. Note that you 0344 /// have to decide whether you want to record in mono or stereo 0345 /// before starting the recording. 0346 /// 0347 /// It is important to note that the audio capture happens in a 0348 /// separate thread, so that it doesn't block the rest of the 0349 /// program. In particular, the onProcessSamples virtual function 0350 /// (but not onStart and not onStop) will be called 0351 /// from this separate thread. It is important to keep this in 0352 /// mind, because you may have to take care of synchronization 0353 /// issues if you share data between threads. 0354 /// Another thing to bear in mind is that you must call stop() 0355 /// in the destructor of your derived class, so that the recording 0356 /// thread finishes before your object is destroyed. 0357 /// 0358 /// Usage example: 0359 /// \code 0360 /// class CustomRecorder : public sf::SoundRecorder 0361 /// { 0362 /// public: 0363 /// ~CustomRecorder() 0364 /// { 0365 /// // Make sure to stop the recording thread 0366 /// stop(); 0367 /// } 0368 /// 0369 /// private: 0370 /// virtual bool onStart() // optional 0371 /// { 0372 /// // Initialize whatever has to be done before the capture starts 0373 /// ... 0374 /// 0375 /// // Return true to start playing 0376 /// return true; 0377 /// } 0378 /// 0379 /// virtual bool onProcessSamples(const sf::Int16* samples, std::size_t sampleCount) 0380 /// { 0381 /// // Do something with the new chunk of samples (store them, send them, ...) 0382 /// ... 0383 /// 0384 /// // Return true to continue playing 0385 /// return true; 0386 /// } 0387 /// 0388 /// virtual void onStop() // optional 0389 /// { 0390 /// // Clean up whatever has to be done after the capture ends 0391 /// ... 0392 /// } 0393 /// }; 0394 /// 0395 /// // Usage 0396 /// if (CustomRecorder::isAvailable()) 0397 /// { 0398 /// CustomRecorder recorder; 0399 /// 0400 /// if (!recorder.start()) 0401 /// return -1; 0402 /// 0403 /// ... 0404 /// recorder.stop(); 0405 /// } 0406 /// \endcode 0407 /// 0408 /// \see sf::SoundBufferRecorder 0409 /// 0410 ////////////////////////////////////////////////////////////
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|