pythonista3使用说明_Pythonista中文文档：sound

sound — 音效和音乐播放

sound模块包含在iOS上播放音效和音频文件的功能。

它还可以使用Recorder类从麦克风录制音频文件。

注意: 为了使用Recorder类，你必须允许访问麦克风。首次使用Recorder.record()方法时，系统会自动显示一个对话框。如果你未授权访问麦克风，则也可以在应用“设置”的“隐私”部分中启用它。

函数

sound.play_effect(name[, volume, pitch=1.0, pan=0.0, looping=False])

使用给定名称播放音效。你可以使用资源管理器（工具栏中的[+]按钮）访问内置音效名称的列表，但是如果你想使用自己的音效，名称也可以是文件路径。

播放是异步的，即函数在声音播放完毕之前返回。

返回值是一个sound.Effect对象，可用于稍后调整播放设置，或在完成播放之前停止音效。

如果已经播放了太多音效（通常限制为32个左右），则可能不会返回任何声音。

sound.stop_all_effects()

停止当前正在播放的所有音效（通过play_effect()）。

sound.stop_effect(effect)

停止播放给定的音效。effect应该是play_effect()的返回值。

sound.set_volume(vol)

设置所有音效的默认音量（介于0.0和1.0之间，默认值为0.5）。这对已经播放的音效没有影响。

sound.set_honors_silent_switch(flag)

确定在播放声音时是否接受静音开关（默认为True）。

音效类

class sound.Effect

Effect类代表当前正在播放的音效。你不能直接创建Effect对象，它们是从play_effect()函数中返回的。对于简单的一次性效果，你可以忽略play_effect()的返回值，但对于在播放效果时调整播放属性（例如音量或音调）或停止循环效果很有用。

音效类的方法

Effect.stop()

停止播放音效。

音效类的属性

Effect.looping

设置为True时，音效将无限循环，直到使用该Effect.stop()方法停止播放为止。

Effect.pan

音效的立体声位置（-1 =左，+ 1 =右，0 =中心）。

Effect.pitch

音效的音调（播放速度）。默认值为1.0。

Effect.position

音效的空间（3D）位置。该值是一个（x，y，z）三元组。请注意，这将覆盖（立体声）Sound.pan属性。

Effect.volume

当前音效的音量。

播放器类

class sound.Player(file_path)

Player类提供了一个易于使用的界面，用于从磁盘播放音频文件。建议对不需要很低延迟的音乐和其他音频使用此类。对于游戏中的音效，play_effect()更合适。

播放器类的方法

Player.play()

开始播放音频。

Player.stop()

停止播放音频并重置播放位置。

Player.pause()

停止播放音频，但保持当前播放位置。

播放器类的属性

Player.current_time

当前播放位置，以秒为单位。

Player.duration

音轨的持续时间（只读）。

Player.finished_handler

播放器结束播放时调用的不带参数的函数/可调用对象。

Player.number_of_loops

音轨应重复的次数。设置为-1可永久重复。

Player.playing

一个布尔值，指示音频播放器是否正在播放。

Player.pan

播放声音的立体声位置（-1 =左，+1 =右，0 =居中）。

录音器类

class sound.Recorder(file_path)

file_path参数指定了在磁盘上创建的音频文件。音频文件格式由文件扩展名自动确定。它应该是.m4a（MPEG4 AAC）或.wav（Linear PCM）。MPEG4音频文件比Wav文件小得多，但是如果要使用该wave模块处理原始音频数据，则可能要使用Wav 。

录音器类的方法

Recorder.record([duration])

开始从麦克风录制音频。如果提供了可选的duration参数，则在经过指定的秒数后，录制会自动停止。否则，必须使用Recorder.stop()方法显式停止记录。

Recorder.stop()

停止录制音频。

Recorder.pause()

暂停录音。可以使用Recorder.record()方法恢复记录。

录音器类的属性

Recorder.current_time

当前活动记录的持续时间。

Recorder.recording

记录器当前是否正在记录（布尔值）。

Recorder.meters

当前的平均功率和峰值功率（只读）。访问此属性会自动启用对此Recorder实例的计数，这可能会消耗额外的处理资源。该值为带有’average‘和’peak‘键的字典，每个键包含用于左右声道的两个数字的元组。范例：{'average': (-35.3, -30.1), 'peak': (-5.2, -8.2)}。

MIDI播放器类的方法

class sound.MIDIPlayer(file_path[, sound_bank_path])

MIDIPlayer使用内置的“Merlin Silver”声音库或你提供的声音库，为MIDI（.mid）文件提供简单的播放功能。如果提供自定义声音库，则它必须为sf2格式。

MIDI播放器类

MIDIPlayer.play()

开始播放。

MIDIPlayer.stop()

停止播放。

MIDI播放器类的属性

MIDIPlayer.current_time

当前播放位置。

MIDIPlayer.duration

加载的MIDI文件的持续时间。

MIDIPlayer.rate

播放速率（正常速度为1.0）。