Ви не можете вибрати більше 25 тем Теми мають розпочинатися з літери або цифри, можуть містити дефіси (-) і не повинні перевищувати 35 символів.

326 lines
14KB

  1. <h3>Summary</h3>
  2. <p>Control the SGTL5000 chip on the
  3. <a href="http://www.pjrc.com/store/teensy3_audio.html" target="_blank">audio shield</a>.
  4. SGTL5000 is always used in slave mode, where Teensy controls
  5. all I2S timing.
  6. </p>
  7. <p align=center><img src="img/sgtl5000closeup.jpg"></p>
  8. <h3>Audio Connections</h3>
  9. <p>This object has no audio inputs or outputs. Separate i2s objects
  10. are used to send and receive audio data. I2S master mode objects
  11. must be used, because this object configures the SGTL5000 in slave
  12. mode, where it depends on Teensy to provide all I2S clocks.
  13. This object controls
  14. how the SGTL5000 will use those I2S audio streams.</p>
  15. <h3>Functions</h3>
  16. <p>These are the most commonly used SGTL5000 functions.</p>
  17. <p class=func><span class=keyword>enable</span>();</p>
  18. <p class=desc>Start the SGTL5000. This function should be called first.
  19. </p>
  20. <p class=func><span class=keyword>volume</span>(level);</p>
  21. <p class=desc>Set the headphone volume level. Range is 0 to 1.0, but
  22. 0.8 corresponds to the maximum undistorted output for a full scale
  23. signal. Usually 0.5 is a comfortable listening level. The line
  24. level outputs are <em>not</em> changed by this function.
  25. </p>
  26. <p class=func><span class=keyword>inputSelect</span>(input);</p>
  27. <p class=desc>Select which input to use: AUDIO_INPUT_LINEIN or AUDIO_INPUT_MIC.
  28. </p>
  29. <p class=func><span class=keyword>micGain</span>(dB);</p>
  30. <p class=desc>When using the microphone input, set the amplifier gain.
  31. The input number is in decibels, from 0 to 63.
  32. </p>
  33. <h3>Signal Levels</h3>
  34. <p>The default signal levels should be used for most applications,
  35. but these functions allow you to customize the analog signals.</p>
  36. <p class=func><span class=keyword>muteHeadphone</span>();</p>
  37. <p class=desc>Silence the headphone output.
  38. </p>
  39. <p class=func><span class=keyword>unmuteHeadphone</span>();</p>
  40. <p class=desc>Turn the headphone output on.
  41. </p>
  42. <p class=func><span class=keyword>muteLineout</span>();</p>
  43. <p class=desc>Silence the line level outputs.
  44. </p>
  45. <p class=func><span class=keyword>unmuteLineout</span>();</p>
  46. <p class=desc>Turn the line level outputs on.
  47. </p>
  48. <p class=func><span class=keyword>lineInLevel</span>(both);</p>
  49. <p class=desc style="padding-bottom:0.2em;">Adjust the sensitivity of the line-level inputs.
  50. Fifteen settings are possible:
  51. </p>
  52. <pre class="desc">
  53. 0: 3.12 Volts p-p
  54. 1: 2.63 Volts p-p
  55. 2: 2.22 Volts p-p
  56. 3: 1.87 Volts p-p
  57. 4: 1.58 Volts p-p
  58. 5: 1.33 Volts p-p (default)
  59. 6: 1.11 Volts p-p
  60. 7: 0.94 Volts p-p
  61. 8: 0.79 Volts p-p
  62. 9: 0.67 Volts p-p
  63. 10: 0.56 Volts p-p
  64. 11: 0.48 Volts p-p
  65. 12: 0.40 Volts p-p
  66. 13: 0.34 Volts p-p
  67. 14: 0.29 Volts p-p
  68. 15: 0.24 Volts p-p
  69. </pre>
  70. <p class=func><span class=keyword>lineInLevel</span>(left, right);</p>
  71. <p class=desc>Adjust the sensitivity of the line-level inputs, with different
  72. settings for left and right. The same 15 settings are available.
  73. </p>
  74. <p class=func><span class=keyword>lineOutLevel</span>(both);</p>
  75. <p class=desc style="padding-bottom:0.2em;">Adjust the line level output
  76. voltage range. The following settings are possible:
  77. </p>
  78. <pre class="desc">
  79. 13: 3.16 Volts p-p
  80. 14: 2.98 Volts p-p
  81. 15: 2.83 Volts p-p
  82. 16: 2.67 Volts p-p
  83. 17: 2.53 Volts p-p
  84. 18: 2.39 Volts p-p
  85. 19: 2.26 Volts p-p
  86. 20: 2.14 Volts p-p
  87. 21: 2.02 Volts p-p
  88. 22: 1.91 Volts p-p
  89. 23: 1.80 Volts p-p
  90. 24: 1.71 Volts p-p
  91. 25: 1.62 Volts p-p
  92. 26: 1.53 Volts p-p
  93. 27: 1.44 Volts p-p
  94. 28: 1.37 Volts p-p
  95. 29: 1.29 Volts p-p (default)
  96. 30: 1.22 Volts p-p
  97. 31: 1.16 Volts p-p
  98. </pre>
  99. <p class=func><span class=keyword>lineOutLevel</span>(left, right);</p>
  100. <p class=desc>Adjust the line level outout voltage range, with separate
  101. settings for left and right. The same settings (13 to 31) are available.
  102. </p>
  103. <h3>Signal Conditioning</h3>
  104. <p>Usually these digital signal conditioning features should be left at their
  105. default settings.
  106. </p>
  107. <p class=func><span class=keyword>adcHighPassFilterFreeze</span>();</p>
  108. <p class=desc>By default, the analog input (either line-level inputs or mic)
  109. is high-pass filtered, to remove any DC component. This function
  110. freezes the filter, so the current DC component is still substracted, but
  111. the filter stops tracking any DC or low frequency changes.
  112. </p>
  113. <p class=func><span class=keyword>adcHighPassFilterDisable</span>();</p>
  114. <p class=desc>Completely disable the analog input filter. DC and sub-audible
  115. low frequencies are allowed to enter the digital signal.
  116. </p>
  117. <p class=func><span class=keyword>adcHighPassFilterEnable</span>();</p>
  118. <p class=desc>Turn the DC-blocking filter back on, if disabled, or
  119. allows it to resume tracking DC and low frequency changes, if
  120. previously frozen. This is the default setting.
  121. </p>
  122. <p class=func><span class=keyword>dacVolume</span>(both);</p>
  123. <p class=desc>Normally output volume should be used with volume(), which
  124. changes the analog gain in the headphone amplifier. This function
  125. on the other hand controls digital attenuation before conversion to analog, which
  126. reduces resolution, but allows another fine control of output
  127. signal level. The ranges is 0 to 1.0, with the default (no digital attenuation)
  128. at 1.0.
  129. </p>
  130. <p class=desc>dacVolume uses zero-crossing detect to avoid clicks, and ramping is handled by
  131. the chip so that a new volume may be set directly in a single call.
  132. </p>
  133. <p class=func><span class=keyword>dacVolume</span>(left, right);</p>
  134. <p class=desc>Adjust the digital output volume separately on left and
  135. right channels.
  136. </p>
  137. <h3>Audio Processor</h3>
  138. <p>The optional digital audio processor is capable of implementing
  139. one or more of: automatic volume control, surround sound control,
  140. bass enhancement, and tonal adjustments (either a
  141. simple tone control, or a parametric equalizer, or a graphic equalizer),
  142. in that order.
  143. </p>
  144. <p>These signal processing features are implemented in the SGTL5000 chip,
  145. so they do not consume CPU time on Teensy. However, the order of
  146. these processes is fixed in the hardware.
  147. </p>
  148. <p>It is good practice to mute the outputs before enabling or disabling
  149. the Audio Processor, to avoid clicks or thumps.
  150. </p>
  151. <p class=func><span class=keyword>audioPreProcessorEnable</span>();</p>
  152. <p class=desc>Enable the audio processor to pre-process the input
  153. (from either line-level inputs or microphone) before it's sent
  154. to Teensy by I2S.
  155. </p>
  156. <p class=func><span class=keyword>audioPostProcessorEnable</span>();</p>
  157. <p class=desc>Enable the audio processor to post-process Teensy's
  158. I2S output before it's turned into analog signals for the
  159. headphones and/or line level outputs.
  160. </p>
  161. <p class=func><span class=keyword>audioProcessorDisable</span>();</p>
  162. <p class=desc>Disable the audio processor.
  163. </p>
  164. <p class=func><span class=keyword>autoVolumeControl</span>(maxGain, response, hardLimit, threshold, attack, decay);</p>
  165. <p class=desc>Configures the auto volume control, which is implemented as a compressor/expander
  166. or hard limiter. <em>maxGain</em> is the maximum gain that can be applied for expanding, and
  167. can take one of three values: 0 (0dB), 1 (6.0dB) and 2 (12dB). Values greater than 2 are treated
  168. as 2. <em>response</em> controls the integration time for the compressor and can take
  169. four values: 0 (0ms), 1 (25ms), 2 (50ms) or 3 (100ms). Larger values average the volume
  170. over a longer time, allowing short-term peaks through.
  171. </p>
  172. <p class=desc>If <em>hardLimit</em> is 0, a 'soft
  173. knee' compressor is used to progressively compress louder values which are near to or above the
  174. threashold (the louder they are, the greater the compression). If it is 1, a hard compressor
  175. is used (all values above the threashold are the same loudness). The <em>threashold</em> is specified
  176. as a float in the range 0dBFS to -96dBFS, where -18dBFS is a typical value.
  177. <em>attack</em> is a float controlling the rate of decrease in gain when the signal is over
  178. threashold, in dB/s. <em>decay</em> controls how fast gain is restored once the level
  179. drops below threashold, again in dB/s. It is typically set to a longer value than attack.
  180. </p>
  181. <p class=func><span class=keyword>autoVolumeEnable</span>();</p>
  182. <p class=desc>Enables auto volume control, using the previously specified settings.
  183. </p>
  184. <p class=func><span class=keyword>autoVolumeDisable</span>();</p>
  185. <p class=desc>Disables auto volume control.
  186. </p>
  187. <p class=func><span class=keyword>surroundSoundEnable</span>();</p>
  188. <p class=desc>Enable virtual surround processing, to give a broader and
  189. deeper stereo image (even with mono input).
  190. </p>
  191. <p class=func><span class=keyword>surroundSoundDisable</span>();</p>
  192. <p class=desc>Disable virtual surround processing. Before disabling, ramp up
  193. the width to maximum to avoid pops.
  194. </p>
  195. <p class=func><span class=keyword>surroundSound</span>(width);</p>
  196. <p class=desc>Configures virtual surround width from 0 (mono) to 7 (widest).
  197. </p>
  198. <p class=func><span class=keyword>surroundSound</span>(width, select);</p>
  199. <p class=desc>Configures virtual surround width from 0 (mono) to 7 (widest).
  200. <em>select</em> may be set to 1 (disable), 2 (mono input) or 3 (stereo input).
  201. </p>
  202. <p class=func><span class=keyword>enhanceBassEnable</span>();</p>
  203. <p class=desc>Enable bass enhancement. A mono, low-pass filtered copy of
  204. the original stereo signal has bass levels boosted and is then mixed back into
  205. the stereo signal, which is then optionally high pass filtered (to remove
  206. inaudible subsonic frequencies).
  207. </p>
  208. <p class=func><span class=keyword>enhanceBassDisable</span>();</p>
  209. <p class=desc>Disable bass enhancement. Before disabling, ramp down the bass
  210. enhancement level to zero.
  211. </p>
  212. <p class=func><span class=keyword>enhanceBass</span>(lr_lev, bass_lev);</p>
  213. <p class=desc>Configures the bass enhancement by setting the levels of the
  214. original stereo signal and the bass-enhanced mono level which will be mixed together.
  215. There is no high-pass filter.
  216. </p>
  217. <p class=desc>When changing bass level, call this function repeatedly to ramp up or down the bass in
  218. steps of 0.5dB, to avoid pops.
  219. </p>
  220. <p class=func><span class=keyword>enhanceBass</span>(lr_lev, bass_lev, hpf_bypass, cutoff);</p>
  221. <p class=desc>Configures the bass enhancement by setting the levels of the
  222. original stereo signal and the bass-enhanced mono level which will be mixed together.
  223. The high-pass filter may be enabled (0) or bypassed (1). The cutoff frequency is specified
  224. as follows:
  225. </p>
  226. <pre class="desc">
  227. value frequency
  228. 0 80Hz
  229. 1 100Hz
  230. 2 125Hz
  231. 3 150Hz
  232. 4 175Hz
  233. 5 200Hz
  234. 6 225Hz
  235. </pre>
  236. <p class=desc>When changing bass level, call this function repeatedly to ramp up or down the bass in
  237. steps of 0.5dB, to avoid pops.
  238. </p>
  239. <p class=func><span class=keyword>eqSelect</span>(n);</p>
  240. <p class=desc>Selects the type of frequency control, where <em>n</em> is
  241. one of</p>
  242. <p class=desc><b>FLAT_FREQUENCY (0)</b><br>
  243. Equalizers and tone controls disabled, flat frequency response.</p>
  244. <p class=desc><b>PARAMETRIC_EQUALIZER (1)</b><br>
  245. Enables the 7-band parametric equalizer, thus disabling the
  246. tone controls and graphic equalizer.</p>
  247. <p class=desc><b>TONE_CONTROLS (2)</b><br>
  248. Enables bass and treble tone controls, disabling the parametric
  249. equalization and graphic equalizer.</p>
  250. <p class=desc><b>GRAPHIC_EQUALIZER (3)</b><br>
  251. Enables the five-band graphic equalizer, disabling the parametric
  252. equalization and tone controls.</p>
  253. <p class=func><span class=keyword>eqBands</span>(bass, treble);</p>
  254. <p class=desc>Configures bass and treble tone controls, which are
  255. implemented as one second order low pass filter (bass) in parallel with
  256. one second order high pass filter (treble).
  257. </p>
  258. <p class=desc>When changing bass or treble level, call this function repeatedly to ramp
  259. up or down the level in steps of 0.04 (=0.5dB) or so, to avoid pops.
  260. </p>
  261. <p class=func><span class=keyword>eqBands</span>(bass, mid_bass, midrange, mid_treble, treble);</p>
  262. <p class=desc>Configures the graphic equalizer. It is implemented by five parallel,
  263. second order biquad filters with fixed frequencies of 115Hz, 330Hz, 990Hz, 3kHz,
  264. and 9.9kHz. Each band has a range of adjustment from 1.00 (+12dB) to -1.00 (-11.75dB).
  265. </p>
  266. <p class=func><span class=keyword>eqBand</span>(bandNum, n);</p>
  267. <p class=desc>Configures the gain or cut on one band in the graphic equalizer.
  268. <em>bandnum</em> can range from 1 to 5; <em>n</em> is a float in the range 1.00 to -1.00.
  269. </p>
  270. <p class=desc>When changing a band, call this function repeatedly to ramp up the gain in steps of 0.5dB,
  271. to avoid pops.
  272. </p>
  273. <p class=func><span class=keyword>eqFilter</span>(filterNum, filterParameters);</p>
  274. <p class=desc>Configurs the parametric equalizer. The number of filters (1 to 7)
  275. is specified along with a pointer to an array of filter coefficients.
  276. The parametric equalizer is implemented using 7 cascaded, second order bi-quad
  277. filters whose frequencies, gain, and Q may be freely configured, but each filter
  278. can only be specified as a set of filter coefficients.
  279. </p>
  280. <p class=func><span class=keyword>eqFilterCount</span>(n);</p>
  281. <p class=desc>Enables zero or more of the already enabled parametric filters.
  282. </p>
  283. <h3>Examples</h3>
  284. <p>Nearly all of the library's examples use this object. These
  285. examples demonstrate its special features.
  286. </p>
  287. <p class=exam>File &gt; Examples &gt; Audio &gt; HardwareTesting &gt; PassThroughStereo
  288. </p>
  289. <p class=exam>File &gt; Examples &gt; Audio &gt; HardwareTesting &gt; SGTL5000 &gt; dap_bass_enhance
  290. </p>
  291. <p class=exam>File &gt; Examples &gt; Audio &gt; HardwareTesting &gt; SGTL5000 &gt; dap_avc_agc
  292. </p>
  293. <p class=exam>File &gt; Examples &gt; Audio &gt; HardwareTesting &gt; SGTL5000 &gt; balanceDAC
  294. </p>
  295. <p class=exam>File &gt; Examples &gt; Audio &gt; HardwareTesting &gt; SGTL5000 &gt; balanceHP
  296. </p>
  297. <p class=exam>File &gt; Examples &gt; Audio &gt; HardwareTesting &gt; SGTL5000 &gt; CalcBiquadToneControlDAP
  298. </p>
  299. <h3>Notes</h3>
  300. <p>TODO: add example with rock/classical/speech presets, where rock uses bass boost
  301. and surround enhancement while speech uses bandpass filtering and auto volume control
  302. compression.
  303. </p>
  304. <p>TODO: add example with two analogRead pots for bass and treble to demonstrate ramping.
  305. </p>