この命令では、音声データをSoundオブジェクト形式と配列形式との間で相互変換できます。このモジュールは、numpyかNumericどちらかの拡張モジュールをインストールしている場合にのみ使用できます。
音声データは1秒あたり数千のサンプルによって構成されており、サンプルとは特定の時点における波の振れ幅のことです。例えば22キロヘルツの音声の場合、配列型音声データの5番目の要素には、22000分の5秒時点での波の振れ幅の値が格納されています。
取得されるサンプルの値は8bitか16bitの整数となり、どちらになるかは音声データの形式によって変わります。ステレオ形式の音声はファイルでは一サンプルあたり二つの値を持ち、モノラル形式の音声はファイルでは一サンプルあたり一つの値を持ちます。
下記の配列形式をサポートしています。
numpy numeric
numpyモジュールがインストールされていた場合、それが既定の配列として使用されます。numpyモジュールがインストールされておらず、Numericモジュールがインストールされていた場合は、そちらが既定の配列として使用されます。numpyライブラリとNumericライブラリのどちらもインストールされていない場合は、ImportErrorのエラーが発生します。
use_arraytype()命令で上記numpyとnumericのどちらかを設定することで、使用する配列の種類を状況に応じて変更することができます。
補足： numpy形式のデータとNumeric形式のデータは完全に互換性があるわけはありません。一方の形式では正常に動作した配列操作が、もう一方の形式では異なる動作をしたりデータを壊してしまったりすることさえあります。
さらに言うと、numpy形式ではNumeric形式と違って符号なしの16bit整数を使用することができます。そのため16bitデータの音声を扱う場合、サンプルデータの種類によっては符号なし整数として扱われます。一方で Numeric形式は、常に符号付整数で値を表します。このpygame.sndarrayの命令を使用して取得された値がおかしいと思ったときは、それぞれの配列形式の違いを思い出してください。
Functions to convert between Numeric or numpy arrays and Sound objects. This module will only be available when pygame can use the external numpy or Numeric package.
Sound data is made of thousands of samples per second, and each sample is the amplitude of the wave at a particular moment in time. For example, in 22-kHz format, element number 5 of the array is the amplitude of the wave after 5/22000 seconds.
Each sample is an 8-bit or 16-bit integer, depending on the data format. A stereo sound file has two values per sample, while a mono sound file only has one.
Supported array systems are
numpy numeric
The default will be numpy, if installed. Otherwise, Numeric will be set as default if installed. If neither numpy nor Numeric are installed, the module will raise an ImportError.
The array type to use can be changed at runtime using the use_arraytype() method, which requires one of the above types as string.
Note: numpy and Numeric are not completely compatible. Certain array manipulations, which work for one type, might behave differently or even completely break for the other.
Additionally, in contrast to Numeric numpy can use unsigned 16-bit integers. Sounds with 16-bit data will be treated as unsigned integers, if the sound sample type requests this. Numeric instead always uses signed integers for the representation, which is important to keep in mind, if you use the module's functions and wonder about the values.
サンプルデータをコピーして、配列形式の音声データを新規に作成します。pygame.mixer.get_init命令で取得される配列形式が使用されます。
Creates a new array for the sound data and copies the samples. The array will always be in the format returned from pygame.mixer.get_init - test if the mixer is initialized.
Soundオブジェクト形式のサンプルデータを参照する配列形式の音声データを、新規に作成します。配列形式のデータを編集すると、元となったSoundオブジェクト形式のデータにもその結果が反映されます。pygame.mixer.get_init命令で取得される配列形式が使用されます。
Creates a new array that directly references the samples in a Sound object. Modifying the array will change the Sound. The array will always be in the format returned from pygame.mixer.get_init - test if the mixer is initialized.
配列型の音声データから、再生可能なSoundオブジェクト型の音声データを新規に作成します。この命令を使用するには、mixerモジュールが初期化されており、引数として渡す配列がmixerの音声形式に対応したものでなければなりません。
Create a new playable Sound object from an array. The mixer module must be initialized and the array format must be similar to the mixer audio format.
この命令で設定したものが、sndarrayモジュールの各命令で使われる配列形式となります。現在は下記の配列形式に対応しています：
numeric numpy
対応していない配列形式を設定した場合、ValueErrorのエラーが発生します。
この命令はpygameのバージョン1.8で新たに実装されました。
Uses the requested array type for the module functions. Currently supported array types are:
numeric numpy
If the requested type is not available, a ValueError will be raised.
New in pygame 1.8.
現在設定されている配列形式名を戻り値として返します。ここで取得できる値は、get_arraytypes()命令で取得できるタプル型の値にも含まれています。タプル型の中で、配列を作成するのに使用される既定の配列モジュールの方が取得されます。
この命令はpygameのバージョン1.8で新たに実装されました。
Returns the currently active array type. This will be a value of the get_arraytypes() tuple and indicates which type of array module is used for the array creation.
New in pygame 1.8
どの配列形式が使用できるかを調べ、使用できるものをタプル型の文字列の戻り値として返します。取得されたタプル型の各値は、pygame.sndarray.use_arraytype()命令の引数としてそのまま使用できます。対応している配列形式が見つからない場合、None値が戻り値として返されます。
この命令はpygameのバージョン1.8で新たに実装されました。
Checks, which array systems are available and returns them as a tuple of strings. The values of the tuple can be used directly in the pygame.sndarray.use_arraytype () method. If no supported array system could be found, None will be returned.
New in pygame 1.8.