📢 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)