init
This commit is contained in:
44
docs/client_html/ar01s13s05.html
Normal file
44
docs/client_html/ar01s13s05.html
Normal file
@@ -0,0 +1,44 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Using custom devices</title><link rel="stylesheet" href="ts3doc.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><link rel="home" href="index.html" title="TeamSpeak 3 Client SDK Developer Manual"><link rel="up" href="ar01s13.html" title="Using playback and capture modes and devices"><link rel="prev" href="ar01s13s04.html" title="Closing devices"><link rel="next" href="ar01s13s06.html" title="Activating the capture device"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><img id="logo" src="images/logo.png"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Using custom devices</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s13s04.html"><img src="images/prev.png" alt="Prev"></a><EFBFBD></td><th width="60%" align="center">Using playback and capture modes and devices</th><td width="20%" align="right"><EFBFBD><a accesskey="n" href="ar01s13s06.html"><img src="images/next.png" alt="Next"></a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="customdevice"></a>Using custom devices</h3></div></div></div><p>Instead of opening existing sound devices that TeamSpeak has detected, you can also use our custom capture and playback mechanism to allow you to override the way in which TeamSpeak does capture and playback. When you have opened a custom capture and playback device you must regularly supply new "captured" sound data via the <code class="function">ts3client_processCustomCaptureData</code> function and retrieve data that should be "played back" via <code class="function">ts3client_acquireCustomPlaybackData</code>. Where exactly this captured sound data comes from and where the playback data goes to is up to you, which allows a lot of cool things to be done with this mechanism.</p><p>Implementing own custom devices is for special use cases and entirely optional.</p><p>Registering a custom device announces the device ID and name to the Client Lib. Once a custom device has been registered under a device ID, the device can be opened like any standard device with <code class="function">ts3client_openCaptureDevice</code> and <code class="function">ts3client_openPlaybackDevice</code>.</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ts3client_registerCustomDevice</b>(</code></td><td><var class="pdparam">deviceID</var>, </td><td><EFBFBD></td></tr><tr><td><EFBFBD></td><td><var class="pdparam">deviceDisplayName</var>, </td><td><EFBFBD></td></tr><tr><td><EFBFBD></td><td><var class="pdparam">capFrequency</var>, </td><td><EFBFBD></td></tr><tr><td><EFBFBD></td><td><var class="pdparam">capChannels</var>, </td><td><EFBFBD></td></tr><tr><td><EFBFBD></td><td><var class="pdparam">playFrequency</var>, </td><td><EFBFBD></td></tr><tr><td><EFBFBD></td><td><var class="pdparam">playChannels</var><code>)</code>;</td><td><EFBFBD></td></tr></table><div class="paramdef-list"><code>const char* <var class="pdparam">deviceID</var></code>;<br><code>const char* <var class="pdparam">deviceDisplayName</var></code>;<br><code>int <var class="pdparam">capFrequency</var></code>;<br><code>int <var class="pdparam">capChannels</var></code>;<br><code>int <var class="pdparam">playFrequency</var></code>;<br><code>int <var class="pdparam">playChannels</var></code>;</div><div class="funcprototype-spacer"><EFBFBD></div></div><a class="indexterm" name="idm44835434608896"></a><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>deviceID</code></em></p><p>ID string of the custom device, under which the device can be later accessed.</p></li><li><p><em class="parameter"><code>deviceDisplayName</code></em></p><p>Displayed name of the custom device. Freely choose a name which identifies your device.</p></li><li><p><em class="parameter"><code>capFrequency</code></em></p><p>Frequency of the capture device.</p></li><li><p><em class="parameter"><code>capChannels</code></em></p><p>Number of channels of the capture device. This value depends on if the used <a class="link" href="ar01s14.html" title="Sound codecs">codec</a> is a mono or stereo codec.</p></li><li><p><em class="parameter"><code>playFrequency</code></em></p><p>Frequency of the playback device.</p></li><li><p><em class="parameter"><code>playChannels</code></em></p><p>Number of channels of the playback device.</p></li></ul></div><p>Returns <em class="structfield"><code>ERROR_ok</code></em> on success, otherwise an error code as defined in <code class="filename">public_errors.h</code>.</p><div class="literallayout"><p><br>
|
||||
</p></div><p>Unregistering a custom device will automatically close the device:</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ts3client_unregisterCustomDevice</b>(</code></td><td><var class="pdparam">deviceID</var><code>)</code>;</td><td><EFBFBD></td></tr></table><div class="paramdef-list"><code>const char* <var class="pdparam">deviceID</var></code>;</div><div class="funcprototype-spacer"><EFBFBD></div></div><a class="indexterm" name="idm44835434592352"></a><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>deviceID</code></em></p><p>ID string of the custom device to unregister. This is the ID under which the device was registered with <code class="function">ts3client_registerCustomDevice</code>.</p></li></ul></div><p>Returns <em class="structfield"><code>ERROR_ok</code></em> on success, otherwise an error code as defined in <code class="filename">public_errors.h</code>.</p><div class="literallayout"><p><br>
|
||||
</p></div><p>To send the captured data from your device to the Client Lib:</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ts3client_processCustomCaptureData</b>(</code></td><td><var class="pdparam">deviceID</var>, </td><td><EFBFBD></td></tr><tr><td><EFBFBD></td><td><var class="pdparam">buffer</var>, </td><td><EFBFBD></td></tr><tr><td><EFBFBD></td><td><var class="pdparam">samples</var><code>)</code>;</td><td><EFBFBD></td></tr></table><div class="paramdef-list"><code>const char* <var class="pdparam">deviceID</var></code>;<br><code>const short* <var class="pdparam">buffer</var></code>;<br><code>int <var class="pdparam">samples</var></code>;</div><div class="funcprototype-spacer"><EFBFBD></div></div><a class="indexterm" name="idm44835434582944"></a><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>deviceID</code></em></p><p>ID string of the custom device. This is the ID under which the device was registered with <code class="function">ts3client_registerCustomDevice</code>.</p></li><li><p><em class="parameter"><code>buffer</code></em></p><p>Capture data buffer containing the data captured by the custom device.</p></li><li><p><em class="parameter"><code>samples</code></em></p><p>Size of the capture data buffer.</p></li></ul></div><p>Returns <em class="structfield"><code>ERROR_ok</code></em> on success, otherwise an error code as defined in <code class="filename">public_errors.h</code>.</p><div class="literallayout"><p><br>
|
||||
</p></div><p>Retrieve playback data from the Client Lib:</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ts3client_acquireCustomPlaybackData</b>(</code></td><td><var class="pdparam">deviceID</var>, </td><td><EFBFBD></td></tr><tr><td><EFBFBD></td><td><var class="pdparam">buffer</var>, </td><td><EFBFBD></td></tr><tr><td><EFBFBD></td><td><var class="pdparam">samples</var><code>)</code>;</td><td><EFBFBD></td></tr></table><div class="paramdef-list"><code>const char* <var class="pdparam">deviceID</var></code>;<br><code>const short* <var class="pdparam">buffer</var></code>;<br><code>int <var class="pdparam">samples</var></code>;</div><div class="funcprototype-spacer"><EFBFBD></div></div><a class="indexterm" name="idm44835434570272"></a><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>deviceID</code></em></p><p>ID string of the custom device. This is the ID under which the device was registered with <code class="function">ts3client_registerCustomDevice</code>.</p></li><li><p><em class="parameter"><code>buffer</code></em></p><p>Buffer containing the playback data retrieved from the Client Lib.</p></li><li><p><em class="parameter"><code>samples</code></em></p><p>Size of the playback data buffer.</p></li></ul></div><p>Returns <em class="structfield"><code>ERROR_ok</code></em> if playback data is available or <em class="structfield"><code>ERROR_sound_no_data</code></em> if the Client Lib currently has no playback data.</p><p>The return value <em class="structfield"><code>ERROR_sound_no_data</code></em> can be used for performance optimisation, it means there is currently only silence (nobody is talking, no wave files being played etc.) and instead of returning a buffer full of zeroes it just notifies the user there is currently no data, which allows you to not playback any sound data for that moment, if your API supports that (potentially saving some CPU), or to just fill the sound buffer with zeroes and playback this if your sound API demands you to fill it with something for every given time.</p><div class="literallayout"><p><br>
|
||||
</p></div><p>Overview on registering and opening a custom device:</p><pre class="programlisting">/* Register a new custom sound device with specified frequency and number of channels */
|
||||
if(ts3client_registerCustomDevice("customWaveDeviceId", "Nice displayable wave device name", captureFrequency, captureChannels, playbackFrequncy, playbackChannels) != ERROR_ok) {
|
||||
printf("Failed to register custom device\n");
|
||||
}
|
||||
|
||||
/* Open capture device we created earlier */
|
||||
if(ts3client_openCaptureDevice(scHandlerID, "custom", "customWaveDeviceId") != ERROR_ok) {
|
||||
printf("Error opening capture device\n");
|
||||
}
|
||||
|
||||
/* Open playback device we created earlier */
|
||||
if(ts3client_openPlaybackDevice(scHandlerID, "custom", "customWaveDeviceId") != ERROR_ok) {
|
||||
printf("Error opening playback device\n");
|
||||
}
|
||||
|
||||
/* Main loop */
|
||||
while(!abort) {
|
||||
/* Fill captureBuffer from your custom device */
|
||||
|
||||
/* Stream your capture data to the client lib */
|
||||
if(ts3client_processCustomCaptureData("customWaveDeviceId", captureBuffer, captureBufferSize) != ERROR_ok) {
|
||||
printf("Failed to process capture data\n");
|
||||
}
|
||||
|
||||
/* Get playback data from the client lib */
|
||||
error = ts3client_acquireCustomPlaybackData("customWaveDeviceId", playbackBuffer, playbackBufferSize);
|
||||
if(error == ERROR_ok) {
|
||||
/* Playback data available, send playbackBuffer to your custom device */
|
||||
} else if(error == ERROR_sound_no_data) {
|
||||
/* Not an error. The client lib has no playback data available. Depending on your custom sound API, either
|
||||
pause playback for performance optimisation or send a buffer of zeros. */
|
||||
} else {
|
||||
printf("Failed to get playback data\n"); /* Error occured */
|
||||
}
|
||||
}
|
||||
|
||||
/* Unregister the custom device. This automatically close the device. */
|
||||
if(ts3client_unregisterCustomDevice("customaveDeviceId") != ERROR_ok) {
|
||||
printf("Failed to unregister custom device\n");
|
||||
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Further sample code on how to use a custom device can be found in the “<span class="quote">client_customdevice</span>” example included in the SDK.</p></td></tr></table></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s13s04.html"><img src="images/prev.png" alt="Prev"></a><EFBFBD></td><td width="20%" align="center"><a accesskey="u" href="ar01s13.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"><EFBFBD><a accesskey="n" href="ar01s13s06.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Closing devices<65></td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"><EFBFBD>Activating the capture device</td></tr></table></div></body></html>
|
||||
Reference in New Issue
Block a user