🎉 ap_ds v3.0.0 LTS 发布公告

发布日期：2026年3月22日

这是一个里程碑式的版本

v3.0.0 是 ap_ds 历史上第一个长期支持版本（LTS）。经过多年的打磨、广泛的实际测试和内部资源管理的彻底重构，我们自豪地推出这个适合关键任务应用、企业部署和个人项目的稳定版本。

为什么选择 LTS？

稳定性、长期可预测性是开发者构建产品、系统和服务的核心需求。v3.0.0 LTS 承诺提供五年的维护支持，包括：

• ✅ 安全更新
• ✅ 关键错误修复
• ✅ 免费技术支持

您可以放心地在 ap_ds 上构建应用，无需担心意外的 API 变更或废弃。

🚀 v3.0.0 LTS 的核心改进

1. 确定性资源清理

解决的问题： 旧版本依赖 Python 的 __del__ 析构函数释放 SDL2 资源，但在某些解释器关闭或异常发生时，资源可能无法正确释放。

解决方案： 使用 atexit 注册显式清理函数，保证所有 SDL2 资源（音频设备、通道、缓存）在程序退出时被正确释放。

2. 哈希验证下载（安全加固）

解决的问题： 旧版本在 SSL 证书验证失败时会回退到未验证的连接，存在理论上的安全风险。

解决方案： 每个下载的 SDL2 库文件都经过硬编码 SHA-256 哈希值验证：

• 哈希匹配 → 使用文件
• 哈希不匹配 → 拒绝并重试

这提供了密码学级别的安全保障，防止中间人攻击和文件篡改。

3. 完整的测试覆盖

在以下环境中通过全部测试：

测试结果： 零内存泄漏，无回归错误。

4. 五年技术支持（2026-2031）

• 开始日期： 2026年3月22日
• 结束日期： 2031年3月22日

在此期间，提供：
- 安全补丁
- 关键错误修复
- 免费技术支持（7个工作日内响应）

5. 100% 向后兼容

• 公共 API 与 v2.x 完全兼容
• 现有代码无需修改即可运行
• 升级只需：pip install --upgrade ap_ds

📦 版本维护与支持策略

LTS 标识

v3.0.0 LTS 及其后续的 v3.0.x 系列（包括 3.0.0、3.0.1、3.0.2 等）被官方指定为 APDSLTS001 支持计划覆盖的版本。

支持期限： 2031年3月22日 23:59:59 UTC

版本分支说明

⚠️ 重要版本信息

🔧 环境变量

📥 立即升级

pip install --upgrade ap_ds

验证安装：

python -c "import ap_ds; print(ap_ds.__version__)"  # 应显示 3.0.0

🔗 官方资源

📧 联系与支持

• 技术问题： GitCode Issues / Gitee Issues
• 授权咨询： me@dvsyun.top 或 dvs6666@163.com
• 响应时间： 标准咨询 7 个工作日，紧急问题 48 小时

感谢您使用 ap_ds！

—— Dvs (DvsXT)

📢 ap_ds v2.4.0 & v2.4.1 发布公告

发布日期：2026年3月1日

概述

v2.4.0 是 ap_ds 的一个重要里程碑版本，引入了专业音频过渡效果和重大工程改进。v2.4.1 紧随其后发布，提供完整的文档更新，确保用户能够充分利用新功能。

注意： 如果您使用的是 v2.4.2，请不要用于生产环境。请升级到 v3.0.0 LTS。

🎵 v2.4.0 新功能：音频过渡效果

最显著的改进是一套完整的淡入/淡出函数，将 ap_ds 从简单的播放库转变为支持专业音频过渡的工具。

新增函数

使用示例

from ap_ds import AudioLibrary
import time

lib = AudioLibrary()

# 2秒淡入
aid = lib.play_from_file("song.mp3")
lib.fadein_music(aid, loops=-1, ms=2000)

# 从30秒位置淡入
lib.fadein_music_pos(aid, loops=-1, ms=1500, position=30.0)

time.sleep(5)

# 3秒淡出
lib.fadeout_music(ms=3000)

# 查询状态
if lib.is_music_playing():
    print("音乐正在播放")

state = lib.get_music_fading()
if state == 1:  # MIX_FADING_OUT
    print("正在淡出...")

🧠 v2.4.0 工程改进

1. 智能欢迎消息

启动横幅现在更简洁且可用户控制：

import ap_ds  # 默认显示: AP_DS © - Audio Library By DVS v2.4.0 | https://apds.top

import os
os.environ['AP_DS_HIDE_SUPPORT_PROMPT'] = '1'
import ap_ds  # 无任何输出

2. 集中式版本管理

版本号现在在 setup.py 中定义一次，自动生成 _version.py，避免版本不一致问题。

3. 健壮的导入系统

两层回退机制确保在所有 Python 环境中都能正常工作：

try:
    from ._version import __version__
except ImportError:
    try:
        from _version import __version__
    except ImportError:
        __version__ = "unknown"

4. 统一项目 URL

所有项目引用现在指向中心枢纽：https://apds.top

📚 v2.4.1：文档更新

虽然 v2.4.0 交付了代码，但 v2.4.1 确保用户能够真正使用它。

更新内容

• ✅ PyPI 项目描述重写：完整反映 v2.4.0 所有新功能
• ✅ 环境变量文档：AP_DS_WAV_THRESHOLD 和 AP_DS_HIDE_SUPPORT_PROMPT
• ✅ 快速入门指南增强：包含迁移示例和常见使用模式
• ✅ 版本历史：从 v1.0.0 到 v2.4.1 的完整变更日志

🔧 环境变量参考

📦 从 v2.3.x 迁移到 v2.4.x

无需修改代码 — 所有现有应用继续正常运行。

要使用新功能：

# 之前 (v2.3.x)
aid = lib.play_from_file("song.mp3")
time.sleep(5)
lib.stop_audio(aid)  # 突然停止

# 之后 (v2.4.0) - 专业过渡！
aid = lib.play_from_file("song.mp3")
lib.fadeout_music(ms=3000)  # 3秒平滑退出

安装/升级

pip install --upgrade ap_ds

⚡ 性能与兼容性

🎯 总结

v2.4.0 将 ap_ds 从"播放库"转变为专业音频工具：

• ✅ 平滑音频过渡（淡入/淡出）
• ✅ 完整状态查询
• ✅ 更干净、更专业的启动体验
• ✅ 工业级版本管理
• ✅ 坚如磐石的导入系统

v2.4.1 确保每个用户都能充分利用这些功能：

• ✅ 全面的 PyPI 文档
• ✅ 详细的代码示例
• ✅ 清晰的环境变量文档

所有这一切都保持核心承诺：轻量级、零外部 Python 依赖、真正的跨平台兼容性。

⚠️ 重要提示

版本 2.2.0 至 2.3.2 存在严重的跨平台 bug，请立即升级。

🔗 相关链接

• 项目主页： https://apds.top
• 主仓库 (GitCode)： https://gitcode.com/dvsxt/ap_ds
• 国内镜像 (Gitee)： https://gitee.com/dssxt/ap_ds
• PyPI： https://pypi.org/project/ap_ds/

感谢您使用 ap_ds！

—— Dvs (DvsXT)