==========================
psychopy.sound
==========================

(訳注：原文のsoundの解説は「心理学実験プログラミング：Python/PsychoPyによる実験作成・データ処理」で述べた内容以上のことはほとんど書かれていないので、ここでは1.85.0のpsychopy/sound/__init__.pyの冒頭に書かれているコメントの抄訳を掲載する)

音楽データを読み込み演奏するモジュールである。

デフォルトではPsychoPyはsounddevice, pygame, pyoの順にライブラリを読み込もうとする。この順序は「設定」の「一般」の「オーディオライブラリ」で変更できる。

portaudioベースのバックエンド(すなわちpygame以外)ではサウンドドライバの選択(ASIO, CoreAudioなど)も可能である。

soundモジュールをimportした後、サウンドライブラリとサウンドドライバは以下の変数に保持される。

- psychopy.sound.audioLib
- psychopy.sound.audioDriver

ビットレートやバッファサイズを制御するには最初にSoundオブジェクトを作成する前にpsychopy.sound.initを呼び出す。

.. code-block:: python

    from psychopy import sound
    sound.init(rate=44100, stereo=True, buffer=128)
    s1 = sound.Sound('ding.wav')

PsychoPyのサウンドライブラリは最初、pygameが選ばれたがレイテンシが常に大きかった。
そこでレイテンシがより短いpyoへ切り替えたが、pyoは非常にシステム依存であった。
pyoの問題はインストール時にコンパイルする必要があることで、コンパイルはいつも大変苦痛で修正が大変であった。
また、2016年の時点でpyoはpython3をサポートしておらず、pipによるインストールもサポートしていなかった。

pysoundcardとsounddeviceは新しいpure pythonなportaudioライブラリで、いずれもpipによるインストールとpython3をサポートしていた。また、オリジナルのpysoundcardのコードと共通部分が多かった。これのライブラリをテストした結果、レイテンシが非常に短いことがわかった。

PsychoPy 1.85の時点では、 **sounddeviceが最もよい選択であるように思われる。** しかし、新たな問題が生じているかも知れない。私たちはsounddeviceのコードを記述する際に音楽の再生開始方法を変更した。pyoもこの新しい方法をサポートしている。なので、公平を期せば、pyoもまたsounddeviceと同様の短いレイテンシを達成できる可能性があると言える。しかし、レイテンシ以外のアドバンテージを考慮するとpyoよりもsounddeviceの方がより優れている。

.. Load and play sounds

.. By default PsychoPy will try to use the following Libs, in this order, for sound reproduction but you can alter the order in preferences > general > audioLib:
..     ['sounddevice', 'pygame', 'pyo']
.. For portaudio-based backends (all except for pygame) there is also a choice of the underlying sound driver (e.g. ASIO, CoreAudio etc).

.. After importing sound, the sound lib and driver being used will be stored as::
..     `psychopy.sound.audioLib`
..     `psychopy.sound.audioDriver`

.. For control of bitrate and buffer size you can call psychopy.sound.init before creating your first Sound object::

..    from psychopy import sound
..    sound.init(rate=44100, stereo=True, buffer=128)
..    s1 = sound.Sound('ding.wav')

.. The history of sound libs in PsychoPy:

..    - we started with pygame but latencies were always poor
..    - we switched to pyo and latencies were better but very system-dependent.
..      The problem with pyo is that it has to be compiled which was always
..      more painful and prevents us from modifying it easily when needed. It
..      also doesn't support python3 as of 2016 and it doesn't support pip for
..      installation (e.g. in Anaconda)
..    - pysoundcard and sounddevice are new pure python portaudio libraries
..      They both install trivially with pip and support python3
..      Sounddevice appears to be under most recent development (and shares a
..      lot of the original pysoundcard code). In testing we've found the
..      latencies to be low

.. As of PsychoPy 1.85 **sounddevice looks like it will be the best option** but while it is new there may be some teething problems! To be fair, when writing the sounddevice code we also changed the method of starting sounds (and pyo also supports the new method). It is likely that pyo can achieve the same low latencies as sounddevice, but the other advantages of sounddevice make it preferable.