Blender 内置 audaspace 的 aud.Handle播放控制句柄 API 完整指南【免费下载链接】blenderOfficial mirror of Blender项目地址: https://gitcode.com/gh_mirrors/bl/blenderaud.Handle 是 Blender 仓库内置音频库 audaspace位于 extern/audaspace为开发者提供的播放句柄类每当aud.Device.play()把一个声音交给设备后返回的 Handle 对象就代表这一次独立的播放实例用来暂停、恢复、停止、跳转、调节音量与音高以及在 3D 设备上控制声源的位置、速度、方向与距离衰减。本篇指南以 handle.rst 的 API 文档为骨架结合 PyHandle.cpp 的绑定实现与 IHandle.h、I3DHandle.h 的 C 接口源码完整讲解 Handle 的全部方法与属性读完即可在 Blender 的 Python 环境import aud中精确控制任意声音的播放过程。一、Handle 是什么一次播放、一个句柄handle.rst 是一个 Sphinx 自动文档桩它通过.. autoclass:: aud.Handle与:members:指令把aud模块中Handle类型的所有成员方法、属性从其源码 docstring 中提取出来生成参考文档。真正定义这个类的是 Python 绑定源码 PyHandle.cpp其类型 docstring 给出了最权威的定义Handle objects are playback handles that can be used to control playback of a sound. If a sound is played back multiple times then there are as many handles.即Handle 是某一次播放的控制对象。同一个 Sound 对象可以被播放多次每次play()都会产生一个独立的 Handle互不干扰。Sound 只是声音的描述惰性对象播放前不做任何音频处理而 Handle 才是正在发生的播放。Handle 的完整生命周期管理体现在 PyHandle.hPython 层的Handle结构体内部保存了一个std::shared_ptrIHandle以Reference_IHandle*形式存储所有方法调用最终都转发到 C 接口IHandle异常统一转换为aud模块的AUDError抛出。C 语言绑定则遵循 index.rst 描述的约定方法形如AUD_Handle_method()属性形如AUD_Handle_property_get/set()首个参数永远是对象本身实现见 AUD_Handle.h。二、获取 Handledevice.play() 的返回值Handle 不会由用户直接构造而是由设备的play()方法返回。以 tutorials.rst 的 Simple Demo 为例#!/usr/bin/python import aud, time device aud.Device() sine aud.Sound.sine(440) square sine.threshold() handle device.play(square) time.sleep(3)对应完整可运行脚本见 simple.py。注意aud.Sound只是描述真正开始出声的时刻是device.play()调用之后此后一切播放行为都通过返回的handle操控。三、播放控制方法pause / resume / stopHandle 的三个方法定义在 PyHandle.cpp 的Handle_methods表中全部无参数、返回bool方法语义返回说明pause()暂停播放True表示暂停成功False表示声音本就不在播放或句柄已失效resume()恢复播放True表示恢复成功False表示声音本就没在暂停或句柄已失效stop()停止播放True表示停止成功注意调用后该句柄即失效handle.pause() # 暂停 handle.resume() # 继续 handle.stop() # 彻底停止此后 handle 不再可用三个方法在 C 层的契约见 IHandle.hpause()在声音未播放或句柄无效时返回 falsestop()之后句柄必然失效docstring 特别用 note 强调 This makes the handle invalid.。这也是stop()与pause()的本质区别——暂停可以恢复停止则是终结。四、播放状态与基础属性除方法外Handle 还有一批控制播放进行时状态的属性注册在 PyHandle.cpp 的Handle_properties表中。以下是非 3D 专属的基础属性4.1status只读判断播放是否仍在进行语义声音处于播放、暂停还是已停止 失效。类型布尔值。绑定实现中通过PyBool_FromLong(getStatus())转换 C 层的Status枚举见 IHandle.hSTATUS_INVALID0、STATUS_PLAYING、STATUS_PAUSED、STATUS_STOPPED因此status在句柄有效时播放/暂停/保留停止为True句柄失效时为False。这正是 player.py 播放完整文件后自动退出的写法while handle.status: time.sleep(0.1)4.2position播放位置秒可读可写读取当前播放位置单位秒double。写入执行 seek 跳转handle.position 3.5表示跳到 3.5 秒处。注意事项seek 是否生效取决于声音源本身的实现IHandle::seek的 warning 明确提示 Whether the seek works or not depends on the sound source某些实时生成的信号源可能不支持任意跳转。4.3loop_count剩余循环次数类型int。语义剩余的循环次数负值表示无限循环。典型用法见 siren.py 中的防空警报示例handle device.play(sound) handle.loop_count -1 # 无限循环4.4pitch音高类型float。改变音高会同时改变播放速度与频率相当于变速变调常用于慢放、快放、特殊音效。4.5volume音量类型float作用于该句柄对应的这一次播放不影响其他句柄与 Sound 本身。4.6keep播完后的驻留行为需谨慎语义当声音到达末尾、不再产生采样数据时是否在设备中保持暂停驻留而非销毁。用途配合position跳转可以实现播完后再跳回开头重播的效果。警告源码 docstring 原文若设为True又忘记stop()等同内存泄漏——句柄会一直存在直到设备被销毁。因此keep是 Handle 属性中最需要生命周期纪律的一项务必在不再需要时显式stop()。handle.keep True handle.position 0 # 播完后跳回起点可再次播放 # ... 结束后务必 handle.stop()五、3D 空间属性位置、速度、方向与衰减当播放所用设备实现了 3D 接口I3DDevice时返回的 Handle 同时实现 3D 句柄接口I3DHandle见 I3DHandle.h从而拥有全套空间属性。该接口以 OpenAL 1.1 规范为蓝本设计。如果设备不是 3D 设备访问这些属性会抛出aud错误错误信息为Device is not a 3D device!见 PyHandle.cpp 的device_not_3d_error。5.1 空间位姿三件套location / velocity / orientation属性类型说明location3 元组(x, y, z)float声源在 3D 空间中的位置velocity3 元组(x, y, z)float声源速度仅用于多普勒Doppler效应计算不会随时间改变位置orientation4 元组四元数(w, x, y, z)float声源朝向坐标系统约定见 I3DHandle.h右手坐标系声源默认朝向 -Z 方向Y 为上方同时orientation目前只对设置了非默认锥形cone参数的声音有实际影响。此外setLocation的文档明确指出位置不会随 velocity 自动积分更新必须由调用方每帧显式设置。经典的环绕音效写法siren.py让声音绕头部画圆import aud, math, time device aud.Device() high aud.Sound.sine(880).limit(0, 0.5).fadein(0, 0.05).fadeout(0.45, 0.5) low aud.Sound.sine(700).limit(0, 0.5).fadein(0, 0.05).fadeout(0.45, 0.5).volume(0.6) sound high.join(low) handle device.play(sound) handle.loop_count -1 start time.time() while time.time() - start 10: angle time.time() - start handle.location [math.sin(angle), 0, -math.cos(angle)]在立体声设备上至少能听到左右声像移动同时教程还提示正确设置handle.velocity即可启用多普勒效应对照参考 siren2.py。5.2 relative相对坐标开关类型bool。语义location、velocity、orientation是相对听者还是绝对坐标。默认值True——这是为了无 3D 需求的普通播放设计的默认行为见 I3DHandle.h 的 note。5.3 距离衰减三件套distance_reference / distance_maximum / attenuation这三个属性配合Device.distance_model距离衰减模型共同决定音量随距离的变化属性类型语义distance_referencefloat参考距离在该距离上音量恰好等于volumedistance_maximumfloat最大距离听者比这更远时声源音量自动降为 0attenuationfloat距离衰减系数参与衰减公式的计算5.4 锥形声源conecone_angle_inner / cone_angle_outer / cone_volume_outer锥形cone属性用于模拟有方向性的声源顶点位于声源location、朝向orientation、高度无限的两个可闻锥cone_angle_inner内锥张角角度制单位度。内锥以内音量正常。cone_angle_outer外锥张角度。外锥以外音量等于cone_volume_outer。cone_volume_outer外锥外侧音量内锥与外锥之间的区域音量按线性插值过渡。注意见 I3DHandle.h 的 note锥形衰减是在句柄整体volume之上叠加生效的。5.5 音量钳制volume_minimum / volume_maximumvolume_minimum声源最小音量。volume_maximum声源最大音量。作用对如距离衰减、锥形衰减导致的音量计算结果进行钳制防止某个方向的声源过响或过弱。同样关联Device.distance_model。5.6 3D 属性速查表属性Python 类型单位/约定说明location(float, float, float)空间单位声源位置velocity(float, float, float)空间单位/秒仅用于多普勒效应orientation(float, float, float, float)四元数(w,x,y,z)声源朝向relativebool—坐标相对听者与否默认 Trueattenuationfloat—距离衰减系数distance_referencefloat空间单位该距离处音量恰为volumedistance_maximumfloat空间单位超出后音量为 0cone_angle_innerfloat度内锥张角内锥内音量正常cone_angle_outerfloat度外锥张角cone_volume_outerfloat—外锥外音量内外锥间线性插值volume_minimumfloat—最小音量钳制volume_maximumfloat—最大音量钳制六、底层原理从 Python 属性到 C 接口理解 Handle 的底层调用链有助于判断每个属性的行为边界。Python 绑定 PyHandle.cpp 采用标准的 CPython 扩展写法类型注册HandleTypeL1054-L1093的tp_methods挂Handle_methodspause/resume/stoptp_getset挂Handle_properties18 个属性tp_doc即类的 API 文档字符串addHandleToModuleL1120-L1124把类型以aud.Handle名字注册进模块。参数解析每个 setter 使用PyArg_Parse校验类型例如location用(fff)、orientation用(ffff)、position用d秒double、loop_count用i、volume/pitch用fkeep/relative用PyBool_Check强校验布尔。异常处理全部方法/属性都包在try/catch中C 层抛出的aud::Exception统一转为AUDError3D 属性通过dynamic_castI3DHandle*探测设备能力失败即报Device is not a 3D device!。C 接口非 3D 行为由 IHandle.h 定义pause/resume/stop、getKeep/setKeep、seek/getPosition、getStatus、getVolume/setVolume、getPitch/setPitch、getLoopCount/setLoopCount、setStopCallback3D 行为由 I3DHandle.h 定义。值得注意的还有setStopCallback——C 层支持在声音播到末尾时注册回调stopCallback供引擎级代码做播完自动回收等管理Python 绑定当前未直接暴露但这是句柄在 C 层的重要能力。从源码结构可以推断Python 层status之所以是布尔而非枚举是因为绑定把Status枚举直接经PyBool_FromLong收窄为有效/失效两类若需要精确区分播放、暂停、保留停止三种状态需在 C/C 层使用IHandle::getStatus()的完整枚举。七、实战综合示例把前文要点串成一个完整的无限循环 3D 环绕 动态音量示例综合 siren.py 与 player.py 的用法#!/usr/bin/python import aud, math, time device aud.Device() sound aud.Sound.sine(440).fadein(0, 0.05).fadeout(0.45, 0.5) handle device.play(sound) handle.loop_count -1 # 无限循环 handle.pitch 1.0 # 正常音高 handle.volume 0.8 # 基准音量 handle.location (0, 0, 0) # 初始位置 handle.velocity (0, 0, 0) # 多普勒速度 start time.time() while time.time() - start 10 and handle.status: angle time.time() - start handle.location [math.sin(angle), 0, -math.cos(angle)] time.sleep(0.02) handle.stop() # 显式停止避免句柄泄漏八、参考与延伸阅读本指南核心文档handle.rstaud.Handle自动 API 参考类族文档device.rst、sound.rst、sequence.rst、sequence_entry.rst、index.rst入门教程tutorials.rst覆盖Device/Sound/Handle三件套Python 绑定实现PyHandle.cpp、PyHandle.hC 接口定义IHandle.h含Status枚举与stopCallback、I3DHandle.hC 绑定AUD_Handle.h可直接运行的示例simple.py、player.py、siren.py、siren2.py、tetris.py【免费下载链接】blenderOfficial mirror of Blender项目地址: https://gitcode.com/gh_mirrors/bl/blender创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Blender 内置 audaspace 的 aud.Handle：播放控制句柄 API 完整指南
Blender 内置 audaspace 的 aud.Handle播放控制句柄 API 完整指南【免费下载链接】blenderOfficial mirror of Blender项目地址: https://gitcode.com/gh_mirrors/bl/blenderaud.Handle 是 Blender 仓库内置音频库 audaspace位于 extern/audaspace为开发者提供的播放句柄类每当aud.Device.play()把一个声音交给设备后返回的 Handle 对象就代表这一次独立的播放实例用来暂停、恢复、停止、跳转、调节音量与音高以及在 3D 设备上控制声源的位置、速度、方向与距离衰减。本篇指南以 handle.rst 的 API 文档为骨架结合 PyHandle.cpp 的绑定实现与 IHandle.h、I3DHandle.h 的 C 接口源码完整讲解 Handle 的全部方法与属性读完即可在 Blender 的 Python 环境import aud中精确控制任意声音的播放过程。一、Handle 是什么一次播放、一个句柄handle.rst 是一个 Sphinx 自动文档桩它通过.. autoclass:: aud.Handle与:members:指令把aud模块中Handle类型的所有成员方法、属性从其源码 docstring 中提取出来生成参考文档。真正定义这个类的是 Python 绑定源码 PyHandle.cpp其类型 docstring 给出了最权威的定义Handle objects are playback handles that can be used to control playback of a sound. If a sound is played back multiple times then there are as many handles.即Handle 是某一次播放的控制对象。同一个 Sound 对象可以被播放多次每次play()都会产生一个独立的 Handle互不干扰。Sound 只是声音的描述惰性对象播放前不做任何音频处理而 Handle 才是正在发生的播放。Handle 的完整生命周期管理体现在 PyHandle.hPython 层的Handle结构体内部保存了一个std::shared_ptrIHandle以Reference_IHandle*形式存储所有方法调用最终都转发到 C 接口IHandle异常统一转换为aud模块的AUDError抛出。C 语言绑定则遵循 index.rst 描述的约定方法形如AUD_Handle_method()属性形如AUD_Handle_property_get/set()首个参数永远是对象本身实现见 AUD_Handle.h。二、获取 Handledevice.play() 的返回值Handle 不会由用户直接构造而是由设备的play()方法返回。以 tutorials.rst 的 Simple Demo 为例#!/usr/bin/python import aud, time device aud.Device() sine aud.Sound.sine(440) square sine.threshold() handle device.play(square) time.sleep(3)对应完整可运行脚本见 simple.py。注意aud.Sound只是描述真正开始出声的时刻是device.play()调用之后此后一切播放行为都通过返回的handle操控。三、播放控制方法pause / resume / stopHandle 的三个方法定义在 PyHandle.cpp 的Handle_methods表中全部无参数、返回bool方法语义返回说明pause()暂停播放True表示暂停成功False表示声音本就不在播放或句柄已失效resume()恢复播放True表示恢复成功False表示声音本就没在暂停或句柄已失效stop()停止播放True表示停止成功注意调用后该句柄即失效handle.pause() # 暂停 handle.resume() # 继续 handle.stop() # 彻底停止此后 handle 不再可用三个方法在 C 层的契约见 IHandle.hpause()在声音未播放或句柄无效时返回 falsestop()之后句柄必然失效docstring 特别用 note 强调 This makes the handle invalid.。这也是stop()与pause()的本质区别——暂停可以恢复停止则是终结。四、播放状态与基础属性除方法外Handle 还有一批控制播放进行时状态的属性注册在 PyHandle.cpp 的Handle_properties表中。以下是非 3D 专属的基础属性4.1status只读判断播放是否仍在进行语义声音处于播放、暂停还是已停止 失效。类型布尔值。绑定实现中通过PyBool_FromLong(getStatus())转换 C 层的Status枚举见 IHandle.hSTATUS_INVALID0、STATUS_PLAYING、STATUS_PAUSED、STATUS_STOPPED因此status在句柄有效时播放/暂停/保留停止为True句柄失效时为False。这正是 player.py 播放完整文件后自动退出的写法while handle.status: time.sleep(0.1)4.2position播放位置秒可读可写读取当前播放位置单位秒double。写入执行 seek 跳转handle.position 3.5表示跳到 3.5 秒处。注意事项seek 是否生效取决于声音源本身的实现IHandle::seek的 warning 明确提示 Whether the seek works or not depends on the sound source某些实时生成的信号源可能不支持任意跳转。4.3loop_count剩余循环次数类型int。语义剩余的循环次数负值表示无限循环。典型用法见 siren.py 中的防空警报示例handle device.play(sound) handle.loop_count -1 # 无限循环4.4pitch音高类型float。改变音高会同时改变播放速度与频率相当于变速变调常用于慢放、快放、特殊音效。4.5volume音量类型float作用于该句柄对应的这一次播放不影响其他句柄与 Sound 本身。4.6keep播完后的驻留行为需谨慎语义当声音到达末尾、不再产生采样数据时是否在设备中保持暂停驻留而非销毁。用途配合position跳转可以实现播完后再跳回开头重播的效果。警告源码 docstring 原文若设为True又忘记stop()等同内存泄漏——句柄会一直存在直到设备被销毁。因此keep是 Handle 属性中最需要生命周期纪律的一项务必在不再需要时显式stop()。handle.keep True handle.position 0 # 播完后跳回起点可再次播放 # ... 结束后务必 handle.stop()五、3D 空间属性位置、速度、方向与衰减当播放所用设备实现了 3D 接口I3DDevice时返回的 Handle 同时实现 3D 句柄接口I3DHandle见 I3DHandle.h从而拥有全套空间属性。该接口以 OpenAL 1.1 规范为蓝本设计。如果设备不是 3D 设备访问这些属性会抛出aud错误错误信息为Device is not a 3D device!见 PyHandle.cpp 的device_not_3d_error。5.1 空间位姿三件套location / velocity / orientation属性类型说明location3 元组(x, y, z)float声源在 3D 空间中的位置velocity3 元组(x, y, z)float声源速度仅用于多普勒Doppler效应计算不会随时间改变位置orientation4 元组四元数(w, x, y, z)float声源朝向坐标系统约定见 I3DHandle.h右手坐标系声源默认朝向 -Z 方向Y 为上方同时orientation目前只对设置了非默认锥形cone参数的声音有实际影响。此外setLocation的文档明确指出位置不会随 velocity 自动积分更新必须由调用方每帧显式设置。经典的环绕音效写法siren.py让声音绕头部画圆import aud, math, time device aud.Device() high aud.Sound.sine(880).limit(0, 0.5).fadein(0, 0.05).fadeout(0.45, 0.5) low aud.Sound.sine(700).limit(0, 0.5).fadein(0, 0.05).fadeout(0.45, 0.5).volume(0.6) sound high.join(low) handle device.play(sound) handle.loop_count -1 start time.time() while time.time() - start 10: angle time.time() - start handle.location [math.sin(angle), 0, -math.cos(angle)]在立体声设备上至少能听到左右声像移动同时教程还提示正确设置handle.velocity即可启用多普勒效应对照参考 siren2.py。5.2 relative相对坐标开关类型bool。语义location、velocity、orientation是相对听者还是绝对坐标。默认值True——这是为了无 3D 需求的普通播放设计的默认行为见 I3DHandle.h 的 note。5.3 距离衰减三件套distance_reference / distance_maximum / attenuation这三个属性配合Device.distance_model距离衰减模型共同决定音量随距离的变化属性类型语义distance_referencefloat参考距离在该距离上音量恰好等于volumedistance_maximumfloat最大距离听者比这更远时声源音量自动降为 0attenuationfloat距离衰减系数参与衰减公式的计算5.4 锥形声源conecone_angle_inner / cone_angle_outer / cone_volume_outer锥形cone属性用于模拟有方向性的声源顶点位于声源location、朝向orientation、高度无限的两个可闻锥cone_angle_inner内锥张角角度制单位度。内锥以内音量正常。cone_angle_outer外锥张角度。外锥以外音量等于cone_volume_outer。cone_volume_outer外锥外侧音量内锥与外锥之间的区域音量按线性插值过渡。注意见 I3DHandle.h 的 note锥形衰减是在句柄整体volume之上叠加生效的。5.5 音量钳制volume_minimum / volume_maximumvolume_minimum声源最小音量。volume_maximum声源最大音量。作用对如距离衰减、锥形衰减导致的音量计算结果进行钳制防止某个方向的声源过响或过弱。同样关联Device.distance_model。5.6 3D 属性速查表属性Python 类型单位/约定说明location(float, float, float)空间单位声源位置velocity(float, float, float)空间单位/秒仅用于多普勒效应orientation(float, float, float, float)四元数(w,x,y,z)声源朝向relativebool—坐标相对听者与否默认 Trueattenuationfloat—距离衰减系数distance_referencefloat空间单位该距离处音量恰为volumedistance_maximumfloat空间单位超出后音量为 0cone_angle_innerfloat度内锥张角内锥内音量正常cone_angle_outerfloat度外锥张角cone_volume_outerfloat—外锥外音量内外锥间线性插值volume_minimumfloat—最小音量钳制volume_maximumfloat—最大音量钳制六、底层原理从 Python 属性到 C 接口理解 Handle 的底层调用链有助于判断每个属性的行为边界。Python 绑定 PyHandle.cpp 采用标准的 CPython 扩展写法类型注册HandleTypeL1054-L1093的tp_methods挂Handle_methodspause/resume/stoptp_getset挂Handle_properties18 个属性tp_doc即类的 API 文档字符串addHandleToModuleL1120-L1124把类型以aud.Handle名字注册进模块。参数解析每个 setter 使用PyArg_Parse校验类型例如location用(fff)、orientation用(ffff)、position用d秒double、loop_count用i、volume/pitch用fkeep/relative用PyBool_Check强校验布尔。异常处理全部方法/属性都包在try/catch中C 层抛出的aud::Exception统一转为AUDError3D 属性通过dynamic_castI3DHandle*探测设备能力失败即报Device is not a 3D device!。C 接口非 3D 行为由 IHandle.h 定义pause/resume/stop、getKeep/setKeep、seek/getPosition、getStatus、getVolume/setVolume、getPitch/setPitch、getLoopCount/setLoopCount、setStopCallback3D 行为由 I3DHandle.h 定义。值得注意的还有setStopCallback——C 层支持在声音播到末尾时注册回调stopCallback供引擎级代码做播完自动回收等管理Python 绑定当前未直接暴露但这是句柄在 C 层的重要能力。从源码结构可以推断Python 层status之所以是布尔而非枚举是因为绑定把Status枚举直接经PyBool_FromLong收窄为有效/失效两类若需要精确区分播放、暂停、保留停止三种状态需在 C/C 层使用IHandle::getStatus()的完整枚举。七、实战综合示例把前文要点串成一个完整的无限循环 3D 环绕 动态音量示例综合 siren.py 与 player.py 的用法#!/usr/bin/python import aud, math, time device aud.Device() sound aud.Sound.sine(440).fadein(0, 0.05).fadeout(0.45, 0.5) handle device.play(sound) handle.loop_count -1 # 无限循环 handle.pitch 1.0 # 正常音高 handle.volume 0.8 # 基准音量 handle.location (0, 0, 0) # 初始位置 handle.velocity (0, 0, 0) # 多普勒速度 start time.time() while time.time() - start 10 and handle.status: angle time.time() - start handle.location [math.sin(angle), 0, -math.cos(angle)] time.sleep(0.02) handle.stop() # 显式停止避免句柄泄漏八、参考与延伸阅读本指南核心文档handle.rstaud.Handle自动 API 参考类族文档device.rst、sound.rst、sequence.rst、sequence_entry.rst、index.rst入门教程tutorials.rst覆盖Device/Sound/Handle三件套Python 绑定实现PyHandle.cpp、PyHandle.hC 接口定义IHandle.h含Status枚举与stopCallback、I3DHandle.hC 绑定AUD_Handle.h可直接运行的示例simple.py、player.py、siren.py、siren2.py、tetris.py【免费下载链接】blenderOfficial mirror of Blender项目地址: https://gitcode.com/gh_mirrors/bl/blender创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考