Mercurial > pygame

annotate lib/sndarray.doc @ 1849:301bc61643a9 math_module

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merged changes from trunk
author lorenz
date Mon, 16 Nov 2009 18:31:40 +0000
parents ac7c93b62b1e
children 4cf10018fadd
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
627
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
1 pygame.sndarray
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
2 pygame module for accessing sound sample data
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
3
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
4 Functions to convert between Numeric or numpy arrays and Sound
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
5 objects. This module will only be available when pygame can use the
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
6 external numpy or Numeric package.
627
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
7
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
8 Sound data is made of thousands of samples per second, and each sample
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
9 is the amplitude of the wave at a particular moment in time. For
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
10 example, in 22-kHz format, element number 5 of the array is the
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
11 amplitude of the wave after 5/22000 seconds.
711
48d403fff022 more doc updates from Dan Richter
pygame
parents: 629
diff changeset
12
48d403fff022 more doc updates from Dan Richter
pygame
parents: 629
diff changeset
13 Each sample is an 8-bit or 16-bit integer, depending on the data format.
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
14 A stereo sound file has two values per sample, while a mono sound file
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
15 only has one.
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
16
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
17 Supported array systems are
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
18
1459
ac7c93b62b1e numpy now takes priority over Numeric in sndarry and surfarray
Lenard Lindstrom <len-l@telus.net>
parents: 927
diff changeset
19 numpy
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
20 numeric
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
21
1459
ac7c93b62b1e numpy now takes priority over Numeric in sndarry and surfarray
Lenard Lindstrom <len-l@telus.net>
parents: 927
diff changeset
22 The default will be numpy, if installed. Otherwise, Numeric will be set
ac7c93b62b1e numpy now takes priority over Numeric in sndarry and surfarray
Lenard Lindstrom <len-l@telus.net>
parents: 927
diff changeset
23 as default if installed. If neither numpy nor Numeric are installed, the
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
24 module will raise an ImportError.
627
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
25
927
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
26 The array type to use can be changed at runtime using the use_arraytype()
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
27 method, which requires one of the above types as string.
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
28
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
29 Note: numpy and Numeric are not completely compatible. Certain array
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
30 manipulations, which work for one type, might behave differently or even
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
31 completely break for the other.
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
32
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
33 Additionally, in contrast to Numeric numpy can use unsigned 16-bit
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
34 integers. Sounds with 16-bit data will be treated as unsigned integers,
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
35 if the sound sample type requests this. Numeric instead always uses
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
36 signed integers for the representation, which is important to keep in
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
37 mind, if you use the module's functions and wonder about the values.
627
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
38 <SECTION>
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
39
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
40 array
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
41 copy Sound samples into an array
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
42 pygame.sndarray.array(Sound): return array
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
43
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
44 Creates a new array for the sound data and copies the samples. The array
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
45 will always be in the format returned from pygame.mixer.get_init().
627
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
46 <END>
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
47
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
48 samples
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
49 reference Sound samples into an array
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
50 pygame.sndarray.samples(Sound): return array
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
51
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
52 Creates a new array that directly references the samples in a Sound
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
53 object. Modifying the array will change the Sound. The array will always
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
54 be in the format returned from pygame.mixer.get_init().
627
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
55 <END>
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
56
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
57 make_sound
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
58 convert an array into a Sound object
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
59 pygame.sndarray.make_sound(array): return Sound
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
60
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
61 Create a new playable Sound object from an array. The mixer module must
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
62 be initialized and the array format must be similar to the mixer audio
627
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
63 format.
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
64 <END>
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
65
927
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
66 use_arraytype
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
67 Sets the array system to be used for sound arrays
927
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
68 pygame.sndarray.use_arraytype (arraytype): return None
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
69
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
70 Uses the requested array type for the module functions.
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
71 Currently supported array types are:
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
72
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
73 numeric
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
74 numpy
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
75
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
76 If the requested type is not available, a ValueError will be raised.
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
77
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
78 New in pygame 1.8.
627
18b5fa9180bf new reference documentation system
pygame
parents:
diff changeset
79 <END>
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
80
927
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
81 get_arraytype
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
82 Gets the currently active array type.
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
83 pygame.sndarray.get_arraytype (): return str
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
84
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
85 Returns the currently active array type. This will be a value of the
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
86 get_arraytypes() tuple and indicates which type of array module is used
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
87 for the array creation.
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
88
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
89 New in pygame 1.8
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
90 <END>
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
91
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
92 get_arraytypes
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
93 Gets the array system types currently supported.
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
94 pygame.sndarray.get_arraytypes (): return tuple
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
95
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
96 Checks, which array systems are available and returns them as a tuple of
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
97 strings. The values of the tuple can be used directly in the
927
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
98 pygame.sndarray.use_arraytype () method. If no supported array system
4a852f241fd3 Added get_arraytype() to sndarray and surfarray for querying the active array type. Renamed use_array() to use_arraytype().
marcus
parents: 898
diff changeset
99 could be found, None will be returned.
898
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
100
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
101 New in pygame 1.8.
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
102 <END>
424ef30fa1ea Added numpy support for the sndarray module. BufferProxy now contains a length property, which indicates the length of the buffer in bytes.
marcus
parents: 711
diff changeset
103 <END>