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

**发布日期：2026年3月1日**

---

## 概述

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

| 版本 | 类型 | 重点 |
|------|------|------|
| **v2.4.1** | 文档更新 | PyPI 文档、示例、环境变量 |
| **v2.4.0** | 功能 + 工程 | 淡入淡出函数、版本管理、导入系统 |

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

---

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

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

### 新增函数

| 函数 | 参数 | 说明 |
|------|------|------|
| `fadein_music(aid, loops=-1, ms=0)` | `aid`: 音频ID<br>`loops`: 循环次数<br>`ms`: 淡入时长(毫秒) | 淡入音乐 |
| `fadein_music_pos(aid, loops=-1, ms=0, position=0.0)` | 同上 + `position`: 起始位置(秒) | 从指定位置淡入 |
| `fadeout_music(ms=0)` | `ms`: 淡出时长(毫秒) | 淡出当前音乐 |
| `is_music_playing()` | 无 | 检查音乐是否正在播放 |
| `is_music_paused()` | 无 | 检查音乐是否暂停 |
| `get_music_fading()` | 无 | 获取淡入淡出状态 |

### 使用示例

```python
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. 智能欢迎消息

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

```python
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 环境中都能正常工作：

```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 的完整变更日志

---

## 🔧 环境变量参考

| 变量 | 默认值 | 说明 | 引入版本 |
|------|--------|------|----------|
| `AP_DS_WAV_THRESHOLD` | `6` | WAV 阈值（秒），≥阈值时支持 seek | v2.3.5 |
| `AP_DS_HIDE_SUPPORT_PROMPT` | 未设置 | 设为 `1` 隐藏启动欢迎消息 | v2.4.0 |

---

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

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

要使用新功能：

```python
# 之前 (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秒平滑退出
```

### 安装/升级

```bash
pip install --upgrade ap_ds
```

---

## ⚡ 性能与兼容性

| 指标 | 数值 |
|------|------|
| 包大小 | Windows: 2.5MB / macOS: 3.36MB / Linux: 依赖系统 SDL2 |
| 内存增长 | 长时间测试后 ~4MB |
| Python 支持 | 3.7+（所有版本） |
| 平台支持 | Windows, macOS, Linux (x86_64, ARM64) |
| API 兼容性 | 100% 向后兼容 v2.3.x |

---

## 🎯 总结

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

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

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

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

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

---

## ⚠️ 重要提示

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

| 版本 | 状态 | 建议 |
|------|------|------|
| **v3.0.0 LTS** | ✅ 最新稳定 | **推荐所有用户使用** |
| v2.4.2 | ⚠️ 开发事故 | 仅供好奇，不要用于生产 |
| v2.4.1 | ✅ 稳定 | 安全，但已被 v3.0.0 取代 |
| v2.4.0 | ✅ 稳定 | 安全，但已被 v3.0.0 取代 |
| v2.3.x | ✅ 稳定 | 安全，但建议升级到 LTS |
| v2.2.0 - v2.3.2 | ❌ 已撤回 | 不要使用 |

---

## 🔗 相关链接

- **项目主页：** 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)*