Mercurial > pygame

annotate docs/reST/ref/sndarray.rst @ 3172:d1b367fc08bc tests-returncode

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use a return code of 1 when the tests fail.
author Thomas Kluyver <takowl@gmail.com>
date Wed, 09 Jan 2013 10:13:57 +0000
parents 2b98dc633495
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2209
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
1 .. include:: common.txt
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
2
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
3 :mod:`pygame.sndarray`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
4 ======================
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
5
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
6 .. module:: pygame.sndarray
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
7 :synopsis: pygame module for accessing sound sample data
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
8
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
9 | :sl:`pygame module for accessing sound sample data`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
10
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
11 Functions to convert between Numeric or numpy arrays and Sound objects. This
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
12 module will only be available when pygame can use the external numpy or Numeric
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
13 package.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
14
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
15 Sound data is made of thousands of samples per second, and each sample is the
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
16 amplitude of the wave at a particular moment in time. For example, in 22-kHz
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
17 format, element number 5 of the array is the amplitude of the wave after
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
18 5/22000 seconds.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
19
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
20 Each sample is an 8-bit or 16-bit integer, depending on the data format. A
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
21 stereo sound file has two values per sample, while a mono sound file only has
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
22 one.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
23
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
24 Supported array systems are
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
25
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
26 ::
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
27
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
28 numpy
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
29 numeric (deprecated; to be removed in Pygame 1.9.3.)
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
30
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
31 The default will be numpy, if installed. Otherwise, Numeric will be set as
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
32 default if installed, and a deprecation warning will be issued. If neither
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
33 numpy nor Numeric are installed, the module will raise an ImportError.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
34
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
35 The array type to use can be changed at runtime using the ``use_arraytype()``
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
36 method, which requires one of the above types as string.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
37
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
38 Note: numpy and Numeric are not completely compatible. Certain array
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
39 manipulations, which work for one type, might behave differently or even
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
40 completely break for the other.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
41
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
42 Additionally, in contrast to Numeric numpy can use unsigned 16-bit integers.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
43 Sounds with 16-bit data will be treated as unsigned integers, if the sound
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
44 sample type requests this. Numeric instead always uses signed integers for the
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
45 representation, which is important to keep in mind, if you use the module's
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
46 functions and wonder about the values.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
47
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
48 numpy support added in Pygame 1.8 Official Numeric deprecation begins in Pygame
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
49 1.9.2.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
50
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
51 .. function:: array
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
52
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
53 | :sl:`copy Sound samples into an array`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
54 | :sg:`array(Sound) -> array`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
55
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
56 Creates a new array for the sound data and copies the samples. The array
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
57 will always be in the format returned from ``pygame.mixer.get_init()``.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
58
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
59 .. ## pygame.sndarray.array ##
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
60
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
61 .. function:: samples
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
62
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
63 | :sl:`reference Sound samples into an array`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
64 | :sg:`samples(Sound) -> array`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
65
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
66 Creates a new array that directly references the samples in a Sound object.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
67 Modifying the array will change the Sound. The array will always be in the
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
68 format returned from ``pygame.mixer.get_init()``.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
69
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
70 .. ## pygame.sndarray.samples ##
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
71
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
72 .. function:: make_sound
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
73
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
74 | :sl:`convert an array into a Sound object`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
75 | :sg:`make_sound(array) -> Sound`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
76
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
77 Create a new playable Sound object from an array. The mixer module must be
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
78 initialized and the array format must be similar to the mixer audio format.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
79
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
80 .. ## pygame.sndarray.make_sound ##
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
81
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
82 .. function:: use_arraytype
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
83
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
84 | :sl:`Sets the array system to be used for sound arrays`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
85 | :sg:`use_arraytype (arraytype) -> None`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
86
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
87 Uses the requested array type for the module functions. Currently supported
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
88 array types are:
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
89
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
90 ::
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
91
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
92 numeric (deprecated; will be removed in Pygame 1.9.3.)
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
93 numpy
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
94
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
95 If the requested type is not available, a ValueError will be raised.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
96
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
97 New in pygame 1.8.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
98
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
99 .. ## pygame.sndarray.use_arraytype ##
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
100
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
101 .. function:: get_arraytype
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
102
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
103 | :sl:`Gets the currently active array type.`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
104 | :sg:`get_arraytype () -> str`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
105
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
106 Returns the currently active array type. This will be a value of the
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
107 ``get_arraytypes()`` tuple and indicates which type of array module is used
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
108 for the array creation.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
109
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
110 New in pygame 1.8
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
111
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
112 .. ## pygame.sndarray.get_arraytype ##
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
113
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
114 .. function:: get_arraytypes
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
115
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
116 | :sl:`Gets the array system types currently supported.`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
117 | :sg:`get_arraytypes () -> tuple`
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
118
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
119 Checks, which array systems are available and returns them as a tuple of
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
120 strings. The values of the tuple can be used directly in the
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
121 :func:`pygame.sndarray.use_arraytype` () method. If no supported array
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
122 system could be found, None will be returned.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
123
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
124 New in pygame 1.8.
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
125
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
126 .. ## pygame.sndarray.get_arraytypes ##
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
127
bb423f0fc96c Add reST document sources and make Sphinx the default document builder
Lenard Lindstrom <len-l@telus.net>
parents:
diff changeset
128 .. ## pygame.sndarray ##