pychram仓库

mixer | Pygame中文文档

pygame.mixer

pygame中用于加载和播放声音的模块

函数

• pygame.mixer.init() —— 初始化 mixer 模块
• pygame.mixer.pre_init() —— 预设混音器初始参数
• pygame.mixer.quit() —— 还原混音器
• pygame.mixer.get_init() —— 测试 mixer 模块是否已被初始化
• pygame.mixer.stop() —— 结束所有通道上的播放
• pygame.mixer.pause() —— 暂停播放所有通道
• pygame.mixer.unpause() —— 恢复播放暂停的通道
• pygame.mixer.fadeout() —— 所有声音以淡出效果结束播放
• pygame.mixer.set_num_channels() —— 设置播放通道的总数
• pygame.mixer.get_num_channels() —— 获取播放通道的总数
• pygame.mixer.set_reserved() —— 保留通道不被自动使用
• pygame.mixer.find_channel() —— 找到一个未使用的通道
• pygame.mixer.get_busy() —— 测试是否有声音正在被混合

类

• pygame.mixer.Sound —— 从文件或缓冲区对象创建一个新的声音对象
• pygame.mixer.Channel —— 创建一个用于控制播放的通道对象

该模块包含加载声音对象和控制播放的类。mixer 模块是可选的，并取决于 SDL_mixer。你的程序应该测试 pygame.mixer 是否可用，并在使用前初始化它。

mixer 模块用来播放声音的通道是有限的。通常当程序告诉 pygame 开始播放音频时， pygame 会自动选择一个可用的通道。同步通道的数量默认为8个，但复杂的程序可以更加精确地控制(增加或者减少)通道数量及使用。

所有声音播放都在后台线程中混合。当你开始播放一个声音对象时，它会在声音继续播放时立即返回。单个声音对象也可以多次有效地播放。

mixer 模块还有一个特殊的流媒体通道。它是一个用于音乐播放的通道，可以通过 pygame.mixer.music 模块调用。

mixer 模块必须像其他 pygame 模块一样初始化，但它有一些额外的条件。pygame.mixer.init() 函数使用几个可选参数来控制播放速率和样本大小。Pygame将参数默认为合理的值，但 pygame 无法执行声音重采样，所以应该初始化混音器来匹配你的音频资源的值。

注意：不要得到较小的声音，并且应当使用较小的缓冲区大小。默认值是为了减少某些计算机上出现磨擦声的机会。您可以通过在调用 pygame.mixer.init() 或 pygame.init() 前调用 pygame.mixer.pre_init() 来更改默认缓冲区大小。例如：

pygame.mixer.pre_init(44100,-16,2, 1024)

在pygame 1.8中，默认缓冲区大小从1024更改为3072。

函数详解

pygame.mixer.init（）

初始化 mixer 模块

init（frequency = 22050，size = -16，channels = 2，buffer = 4096） - > None

初始化 mixer 模块以进行声音加载和播放。默认参数可以被覆盖以提供特定的音频混合。该函数接受关键字参数。为了向后的兼容性，当参数被设置为零时，将使用默认值（可能被调用 pre_init() 更改）。

size 参数表示每个音频实例有多少位。如果该值为负值，则将使用预设的样本值。正值表示将使用非预设的音频采样。无效值引发异常。

channel 参数用于指定是使用单声道还是立体声。1 为单声道，2 为立体声。不支持其他值（负值被视为1，大于2的值被视为2）。

buffer 参数控制混音器中使用的内部采样的数量。默认值应该适用于大多数情况。可以降低该参数值以减少延迟，但可能会发生声音丢失。可以提高该参数值以确保播放不会遗漏，但会对声音播放造成延迟。buffer 的大小必须是2的幂（如果不是，它会被舍入到下一个最接近的2的幂）。

一些平台要求 pygame.mixer 在 display 模块初始化后进行初始化。顶层的 pygame.init() 会自动处理这个问题，但不能将任何参数传递给调音台进行初始化。为了解决这个问题，混音器有一个函数 pygame.mixer.pre_init() 可以在调用 pygame.init() 前设置适当的默认值。

多次调用该函数是可靠的，但是在调音台初始化之后，如果不先调用 pygame.mixer.quit()，你将无法更改播放参数。

pygame.mixer.pre_init（）

预设混音器初始参数

pre_init（frequency = 22050，size = -16，channels = 2，buffersize = 4096） - > None

调用 pre_init() 更改实际 pygame.mixer.init() 被调用时使用的默认值 。该函数接受关键字参数。设置自定义混音器播放值的最佳方式是在调用顶层 pygame.init() 之前调用 pygame.mixer.pre_init()。为了向后的兼容性，值为零的参数会被替换为默认启动值。

pygame.mixer.quit（）

还原混音器

quit() -> None

该函数将会还原 pygame.mixer 模块。如果稍后重新初始化，所有播放都将停止，并且加载的任何声音对象都可能与混音器不兼容。

pygame.mixer.get_init（）

测试混音器是否已被初始化

get_init() -> (frequency, format, channels)

如果混音器已经初始化，该函数会返回正在使用的播放参数。如果混音器没有被初始化，则返回 None

pygame.mixer.stop（）

结束所有通道上的播放

stop（） - > None

该函数将结束所有有效的混音器通道上的所有播放。

pygame.mixer.pause（）

暂停播放所有通道

pause() -> None

该函数将暂时停止有效的混音器通道上的所有播放。之后可以通过调用 pygame.mixer.unpause() 来恢复播放。

pygame.mixer.unpause（）

恢复播放暂停的通道

unpause（） - > None

该函数将恢复播放所有暂停后的有效通道。

pygame.mixer.fadeout（）

所有声音以淡出效果结束播放

fadeout(time) -> None

该函数将会在淡出（也就是不在有声音放出）一段指定长度的时间（以毫秒为单位）后结束播放。声音完全消失后， 播放才会停止。

pygame.mixer.set_num_channels（）

设置播放通道的总数

set_num_channels（count） - > None

设置混音器的可用通道数量。默认值是8.该值可以增加或减少。如果数值降低，被关闭通道播放的声音将停止。

pygame.mixer.get_num_channels（）

获取播放通道的总数

get_num_channels（） - > count

返回当前有效的通道数量。

pygame.mixer.set_reserved（）

保留通道不被自动使用

set_reserved（count） - > None

混音器可以保留任何数量的通道，这些通道不会被声音对象自动选择进行播放。如果声音正在保留通道播放，则不会停止播放。

这允许应用程序为重要的不能被删除的或是必须有一个有保证的通道播放的声音保留特定数量的通道。

pygame.mixer.find_channel（）

找到一个未使用的通道

find_channel（force = False） - > Channel

此函数将会找到并返回一个空闲的Channel对象。如果没有不活动的通道，此功能将返回 None。如果没有空闲的通道，并且 force 参数为 True，则会找到运行时间最长的通道并将其返回。

如果混音器已经调用 pygame.mixer.set_reserved() 设置 保留通道，那么这些通道将不会被这个函数返回。

pygame.mixer.get_busy（）

测试是否有声音正在被混合

get_busy（） - > bool

如果混音器正忙于混音任何通道，则返回 True。如果混音器空闲，则返回 False。

pygame.mixer.Sound

从文件或缓冲区对象创建一个新的声音对象

Sound(filename) -> Sound
Sound(file=filename) -> Sound
Sound(buffer) -> Sound
Sound(buffer=buffer) -> Sound
Sound(object) -> Sound
Sound(file=object) -> Sound
Sound(array=object) -> Sound

方法

• pygame.mixer.Sound.play() —— 开始播放声音
• pygame.mixer.Sound.stop() —— 停止播放声音
• pygame.mixer.Sound.fadeout() —— 以淡出效果结束播放声音
• pygame.mixer.Sound.set_volume() —— 设置此声音对象的播放音量
• pygame.mixer.Sound.get_volume() —— 获取播放音量
• pygame.mixer.Sound.get_num_channels() —— 计算该声音对象播放的次数
• pygame.mixer.Sound.get_length() —— 获取声音的长度
• pygame.mixer.Sound.get_raw() —— 返回声音对象的字节串副本。

从文件名，python文件对象或可读的缓冲对象加载新的声音缓冲。将执行有限的重采样以帮助该对象匹配混音器的初始化参数。一个Unicode字符串只能是一个文件路径名。Python 2.x 字符串或 Python 3.x 字节对象可以是路径名或缓冲区对象。使用'file'或'buffer'关键字以避免含糊不清; 否则声音对象可能会猜错。如果使用array关键字，则该对象需要导出版本3，C级别数组接口，或者对于Python 2.6或更高版本，导出新的缓冲区接口（首先检查该对象是否为缓冲区接口。）

声音对象表示实际的声音采样数据。改变声音对象状态的方法将会影响声音播放的所有实例。声音对象还会导出一个数组接口，对于Python 2.6或更高版本，则会导出一个新的缓冲接口。

声音对象可以从OGG音频文件或未压缩的WAV中加载。

注意：缓冲区将在内部复制，它和声音对象之间不会共享数据。

现在缓冲区和数组支持与 Numeric arrays 中 sndarray.make_sound 一致，在这个样本符号和字节顺序将被忽略。除非通过正确处理符号和字节顺序，或者在不同时引发异常，否则将会导致数据发生改变。此外，源样本还会被截断以适应音频样本大小，该操作不会导致数据发生改变。

pygame 1.8 新增 pygame.mixer.Sound(buffer) 
pygame 1.9.2 新增对数组接口的支持

play（）

开始播放声音

play(loops=0, maxtime=0, fade_ms=0) -> Channel

在可用通道对象上开始播放此声音对象（即在电脑的扬声器上）。该方法将强制选择一个通道对象，因此如有必要，播放可能会切断正在播放的声音。

loops 参数控制对象在第一次播放后会重复多少次。值为5表示声音将播放一次，然后重复五次，总共播放六次。默认值（零）表示声音对象不会重复，所以只播放一次。如果循环设置为-1，则声音将无限循环（尽管您仍然可以调用 stop() 来停止它）。

maxtime 参数可用于在给定的毫秒数量后停止播放。

fade_ms 参数将使声音以0音量开始播放，并在给定的时间内逐渐恢复为全音量。样本可能会在淡入完成之前结束。

该方法将返回所选通道的Channel对象。

stop（）

停止播放声音

stop（） - > None

该方法将在所有当前播放此声音对象的频道上停止播放此声音对象。

fadeout（）

以淡出效果结束播放声音

fadeout(time) -> None

该方法将会在声音淡出一段指定长度的时间后结束播放。此声音对象将会淡出并停止在所有正在播放该声音对象的通道上的播放。

set_volume（）

设置此声音对象的播放音量

set_volume（value） - > None

该方法将设置此声音对象的播放音量（响度）。如果正在播放，该方法将立即影响声音对象。它也会影响此声音对象未来的播放。value 是一个从0.0到1.0的值。

get_volume（）

获取播放音量

get_volume() -> value

该方法将返回一个从0.0到1.0的值，代表这个声音对象的音量。

get_num_channels（）

计算该声音对象播放的次数

get_num_channels（） - > count

该方法将返回此声音对象在当前通道上的播放次数。

get_length（）

获取声音的长度

get_length() -> seconds

以秒为单位返回此声音的长度。

get_raw（）

返回声音对象的字节串副本。

get_raw() -> bytes

该方法会将声音对象缓冲区的副本作为 bytes 对象（对于Python 3.x）或 str 对象（对于Python 2.x）返回。

pygame中的新功能1.9.2。

pygame.mixer.Channel

创建一个用于控制播放的频道对象

Channel(id) -> Channel

方法

• pygame.mixer.Channel.play() —— 在特定通道上播放声音
• pygame.mixer.Channel.stop() —— 停止播放通道
• pygame.mixer.Channel.pause() —— 暂停播放一个通道
• pygame.mixer.Channel.unpause() —— 恢复播放一个暂停播放的通道
• pygame.mixer.Channel.fadeout() —— 以淡出效果结束通道上的播放
• pygame.mixer.Channel.set_volume() —— 设置播放通道的音量
• pygame.mixer.Channel.get_volume() —— 获取播放通道的音量
• pygame.mixer.Channel.get_busy() —— 检查通道是否处于活动状态
• pygame.mixer.Channel.get_sound() —— 获取当前播放的声音
• pygame.mixer.Channel.queue() —— 将一个声音对象排队在当前播放的声音对象之后
• pygame.mixer.Channel.get_queue() —— 返回队列中的所有声音对象
• pygame.mixer.Channel.set_endevent() —— 播放停止时让通道发送事件
• pygame.mixer.Channel.get_endevent() —— 获取播放停止时通道发送的事件

Channel对象可以用来精确控制声音的播放。一个通道只能同时播放一个声音。使用通道是完全可选的，因为pygame可以默认管理它们。

方法详解

play（）

在特定通道上播放声音

play(Sound, loops=0, maxtime=0, fade_ms=0) -> None

该方法将开始播放特定通道上的声音。如果通道正在播放其他声音，正在播放的声音将会停止。

loops 参数的含义与 Sound.play() 中的相同：它是第一次后重复声音的次数。如果是3，声音将播放4次（第一次，然后是三次）。如果 loops 为-1，则播放将无限期重复。

和 Sound.play() 中的一样，可以使用 maxtime 参数在给定的毫秒数之后停止播放声音。

和 Sound.play() 中的一样，可以使用fade_ms参数淡入效果开始播放声音。

stop（）

停止播放通道

stop（） - > None

在通道上停止播放声音。播放停止后，通道可用于播放新的声音。

pause（）

暂停播放一个通道

pause() -> None

暂停播放通道上的声音。它可以在稍后调用Channel.unpause()恢复播放。

unpause（）

恢复播放一个暂停播放的通道

unpause（） - > None

在暂停的通道上继续播放。

fadeout（）

以淡出效果结束通道上的播放

fadeout(time) -> None

该方法将会在淡出播放一段指定长度的时间（以毫秒为单位）后结束通道上的播放。

set_volume（）

设置播放通道的音量

set_volume(value) -> None
set_volume(left, right) -> None

设定播放声音的音量（响度）。当频道开始播放时，音量值会被重置。该方法只影响当前的声音。value 参数值介于0.0和1.0之间。

如果一个参数被通过，它将是两个扬声器的音量。如果传递了两个参数并且混音器处于立体声模式，则第一个参数将是左扬声器的音量，第二个参数将是右扬声器的音量。（如果第二个参数是None，那么第一个参数将是两个扬声器的音量。）

如果频道正在播放的是已调其用 set_volume() 方法的声音对象，两个调用都会被考虑到。例如：

sound = pygame.mixer.Sound("s.wav")channel = s.play() # 声音默认按满音量播放sound.set_volume(0.9) # 现在按满音量的 90% 播放sound.set_volume(0.6) # 现在按 60% 播放(替换之前的值).channel.set_volume(0.5) # 现在按 30% 播放 (0.6 * 0.5).

get_volume（）

获取播放通道的音量

get_volume() -> value

返回当前播放声音的通道音量。该方法没有考虑到使用 Channel.set_volume() 的立体声分离 。声音对象也有自己的音量，会与通道音量混合在一起。

get_busy（）

检查通道是否处于活动状态

get_busy（） - > bool

如果通道当前正在混音，则返回 true。如果通道空闲，则返回 False。

get_sound（）

获取当前播放的声音

get_sound() -> Sound

返回当前实际在此频道上播放的声音对象。如果通道空闲，则返回 None。

Channel.queue（）

将一个声音对象排队在当前播放的声音对象之后

queue(Sound) -> None

声音在频道上排队时，将在当前声音结束后立即开始播放。每个频道一次只能排队一个声音。排队的声音只会在当前播放自动完成时播放。其他声音调用 Channel.stop() 或 Channel.play() 会将其从队列中清除掉

如果 Channel 上没有正在播放的声音，则声音将立即开始播放。

get_queue（）

返回队列的所有声音对象

get_queue() -> Sound

如果一个声音对象已经在这个通道队列中，它将被返回。一旦队列中的声音开始播放，它将不再处于队列中。

set_endevent（）

播放停止时让通道发出一个事件

set_endevent（） - > None
set_endevent（type） - > None

当一个endevent被设置给一个通道时，每次在该通道上播放一个声音时（不仅是第一次），它将发送一个事件给pygame队列。一旦它被发送， 可以使用 pygame.event.get()获取 endevent 。

请注意，如果您调用 Sound.play(n) 或 Channel.play(sound,n) 在声音播放“n + 1”次后（请参阅Sound.play文档）结束事件只发送一次。

如果当声音还在被播放时调用 Channel.stop() 或 Channel.play() ，该事件将被立即发送。

type 参数将是被发送到队列事件的 id 。这个参数值可以是任何有效的事件类型，但是一个好的选择是 pygame.locals.USEREVENT 和 pygame.locals.NUMEVENTS 中间的一个。如果没有给出 type 参数，那么通道将停止发送 endevent。

get_endevent（）

获取播放停止时通道发送的事件

get_endevent() -> type

返回通道完成声音时被放入队列的事件类型。 
如果没有指定 endevent 事件，此方法会返回 pygame.NOEVENT 。