Versions v2.2.0 through v2.3.2 contain a serious cross-platform compatibility issue, causing the library to fail on non-Windows operating systems (macOS and Linux). Subsequent versions have fixed this problem.
Please immediately run pip install --upgrade ap_ds to upgrade to the latest stable version v2.4.1.
We sincerely apologize for the inconvenience caused by earlier versions. We have now ensured the library's integrity and functionality across all supported platforms.
Official info
Project name: ap_ds (v2.4.1)
Website: https://www.apds.top
PyPI: https://pypi.org/project/ap_ds/
Developer: Dvs (DvsXT)
Personal page: https://dvsyun.top/me/dvs
ap_ds is an ultra-lightweight Python audio library of only 2.5MB, designed for high-quality playback and precise metadata parsing of four major formats: MP3, FLAC, OGG, and WAV. Zero external Python dependencies, with a non-blocking playback architecture that makes GUI applications run smoothly.
Complete solution at only 2.5MB (Windows) / 3.36MB (macOS)
Uses only the standard library
WAV/FLAC 100%, OGG 99.99%, MP3 >98%
Perfectly suited for GUI applications
Windows, macOS, Linux, Embedded ARM64
Automatically records playback history, stores only metadata
In the 2026 Python ecosystem, a sharp contradiction has haunted developers for nearly two decades: the irreconcilable gap between completeness and lightweight projects. When your project needs audio playback, you face a painful choice:
This is not a choice — it is a matter of developer dignity. Today, this ends. Created by Dvs (DvsXT), ap_ds (v2.4.1), released 2026-03-01, is a precise revolution in Python audio.
# Pygame's unreliable audio duration
my_sound = pygame.mixer.Sound('my_song.mp3')
total_length = my_sound.get_length() # reliable only for uncompressed WAV!Sound.get_length() works correctly only for WAV; MP3/OGG/FLAC return nonsense.| Component | Function | Size | Total |
|---|---|---|---|
| ffplay.exe | playback core | ≈80MB | ≥160MB |
| ffprobe.exe | metadata probe | ≈80MB | |
| ffmpeg.exe | converter | ≈80MB | ≥240MB |
Seven technical breakthroughs
pip install ap_dsfrom ap_ds import AudioLibrary
lib = AudioLibrary()
aid = lib.play_from_file("music.mp3")
lib.pause_audio(aid)
lib.seek_audio(aid, 30.5)
duration = lib.stop_audio(aid)aid1 = lib.play_from_file("song1.mp3")
recordings = lib.get_dap_recordings()
lib.save_dap_to_json("my_playlist.ap-ds-dap")Current Stable Version: v2.4.1 (Released March 1, 2026)
fadein_music(), fadein_music_pos(), fadeout_music()is_music_playing(), is_music_paused(), get_music_fading()AP_DS_HIDE_SUPPORT_PROMPT_version.pypip install ap_ds
To upgrade from an older version:
pip install --upgrade ap_ds
from ap_ds import AudioLibrary
# Initialize the library
lib = AudioLibrary()
# Play an audio file
aid = lib.play_from_file("music/song.mp3")
# Control playback
lib.pause_audio(aid) # Pause
lib.play_audio(aid) # Resume
lib.seek_audio(aid, 30.5) # Seek to 30.5 seconds
# Stop and get duration played
duration = lib.stop_audio(aid)
print(f"Played for {duration:.2f} seconds")
Audio files are automatically recorded to DAP (Dvs Audio Playlist) upon playback:
# Files are automatically recorded
aid1 = lib.play_from_file("song1.mp3")
aid2 = lib.play_from_file("song2.ogg")
# Get all recordings
recordings = lib.get_dap_recordings()
print(f"Recorded {len(recordings)} files")
# Save to JSON
success = lib.save_dap_to_json("my_playlist.ap-ds-dap")
DAP stores only metadata (path, duration, bitrate, channels), not audio data. Memory usage is approximately 150 bytes per recording.
Intelligent Multi-Layer Import System:
Package Manager Support:
# Ubuntu/Debian
sudo apt-get install libsdl2-dev libsdl2-mixer-dev
# Fedora
sudo dnf install SDL2-devel SDL2_mixer-devel
# Arch
sudo pacman -S sdl2 sdl2_mixer
Tested on:
Both run Ubuntu 22.04 with full audio support via 3.5mm output. Memory growth after extensive testing: ~4MB.
Controls whether WAV files use sound effect mode (no seek) or music mode (full seek):
# Set threshold to 10 seconds (default: 6)
export AP_DS_WAV_THRESHOLD=10
# Files < threshold → sound effect mode (no seek)
# Files >= threshold → music mode (full seek)
Validation Rules:
For custom-compiled SDL2 libraries:
export AP_DS_SDL2_PATH=/usr/local/lib/libSDL2.so
export AP_DS_SDL2_MIXER_PATH=/usr/local/lib/libSDL2_mixer.so
Paths are automatically saved to ~/.config/ap_ds/sdl_paths.conf after first use.
On some older or enterprise-configured systems, you might encounter SSL certificate verification errors during the initial download of SDL2 libraries:
SSL certificate verification failed: unable to get local issuer certificate
Common Causes:
ap_ds implements a layered download strategy:
def download_with_ssl(url):
try:
# First attempt: Standard SSL verification
return urllib.request.urlopen(url)
except SSL error:
# Second attempt: Unverified context (compatibility mode)
# Only triggered when standard verification fails
return download_with_unverified_context(url)
Is this safe? Yes.
Limited Scope: Unverified context is ONLY used for downloading two specific DLLs (SDL2 and SDL2_mixer) from official sources.
Fallback Only: Standard verification is ALWAYS tried first. Unverified mode is only a fallback for legitimate certificate issues.
Limited Capability: Even if a DLL were tampered with (extremely unlikely), SDL2 libraries are audio renderers with:
Attack Economics: Creating a functional malicious replacement for SDL2 requires:
The cost dramatically outweighs any potential benefit.
Multi-Layer Protection: Any malicious behavior would be immediately detected by:
If you have security concerns, manually download the libraries:
__init__(frequency=44100, format=MIX_DEFAULT_FORMAT, channels=2, chunksize=2048)
| Method | Description | Return |
|---|---|---|
play_from_file(path, loops=0, start_pos=0.0) |
Play audio from file | int (AID) |
play_from_memory(path, loops=0, start_pos=0.0) |
Play from cache | int (AID) |
new_aid(path) |
Pre-load audio into memory | int (AID) |
pause_audio(aid) |
Pause playback | None |
play_audio(aid) |
Resume playback | None |
stop_audio(aid) |
Stop and free resources | float (duration) |
seek_audio(aid, position) |
Seek to position (seconds) | None |
set_volume(aid, volume) |
Set volume (0-128) | bool |
get_volume(aid) |
Get current volume | int |
get_audio_duration(source, is_file=False) |
Get duration | int (seconds) |
get_audio_metadata(source, is_file=False) |
Get metadata | Dict or None |
| Method | Description | Return |
|---|---|---|
save_dap_to_json(path) |
Save DAP records to JSON | bool |
get_dap_recordings() |
Get all DAP records | List[Dict] |
clear_dap_recordings() |
Clear DAP records | None |
Version 2.4.0 marks a significant milestone in ap_ds evolution, introducing professional audio transitions and major engineering improvements under the hood. v2.4.1 follows immediately with complete documentation updates to ensure users can fully leverage the new features.
| Version | Release Date | Type | Focus |
|---|---|---|---|
| v2.4.1 | March 1, 2026 | Documentation | PyPI docs, examples, environment variables |
| v2.4.0 | March 1, 2026 | Feature + Engineering | Fade functions, version management, import system |
The most visible addition is a complete set of fade in/out functions, transforming ap_ds from a simple playback library into a tool capable of professional audio transitions.
| Function | Description | Parameters |
|---|---|---|
fadein_music(aid, loops=-1, ms=0) |
Fade in audio over specified milliseconds | aid: Audio instance IDloops: -1 = infinite, 0 = once, N = N timesms: Fade duration in milliseconds |
fadein_music_pos(aid, loops=-1, ms=0, position=0.0) |
Fade in from specific position | Same as above, plus:position: Start position in seconds |
fadeout_music(ms=0) |
Fade out currently playing music | ms: Fade duration in milliseconds |
is_music_playing() |
Check if music is currently playing | None |
is_music_paused() |
Check if music is paused | None |
get_music_fading() |
Get current fade state | Returns: 0 (no fade), 1 (fading out), 2 (fading in) |
from ap_ds import AudioLibrary
import time
lib = AudioLibrary()
# Basic fade in over 2 seconds
aid = lib.play_from_file("song.mp3")
lib.fadein_music(aid, loops=-1, ms=2000)
# Fade in from the 30-second mark
aid2 = lib.play_from_file("podcast.mp3")
lib.fadein_music_pos(aid2, loops=1, ms=1500, position=30.0)
# Let it play for a while
time.sleep(5)
# Smooth fade out over 3 seconds
lib.fadeout_music(ms=3000)
# Query states
if lib.is_music_playing():
print("Music is playing")
fade_state = lib.get_music_fading()
if fade_state == 1: # MIX_FADING_OUT
print("Fading out...")
These functions directly wrap the following SDL2_mixer APIs:
Mix_FadeInMusic() → fadein_music()Mix_FadeInMusicPos() → fadein_music_pos()Mix_FadeOutMusic() → fadeout_music()Mix_PlayingMusic() → is_music_playing()Mix_PausedMusic() → is_music_paused()Mix_FadingMusic() → get_music_fading()The startup banner is now cleaner and user-controllable:
# Default behavior (shows once when library loads)
import ap_ds
# Output: AP_DS © - Audio Library By DVS v2.4.0 | https://www.apds.top
# Silence it completely with environment variable
import os
os.environ['AP_DS_HIDE_SUPPORT_PROMPT'] = '1'
import ap_ds # No output at all
Why this matters:
Version is now defined once in setup.py and automatically generates _version.py:
# setup.py
VERSION = "2.4.0"
def write_version_file():
version_file_path = os.path.join("ap_ds", "_version.py")
with open(version_file_path, "w", encoding="utf-8") as f:
f.write(f'__version__ = "{VERSION}"\n')
Benefits:
Two-layer fallback ensures compatibility across all Python environments:
# Version import with fallback
try:
from ._version import __version__
except ImportError:
try:
from _version import __version__
except ImportError:
__version__ = "unknown"
# Core module import with same pattern
try:
from .player import *
except ImportError:
from player import *
Why this is important:
All project references now point to the central hub: https://www.apds.top
This consolidates:
While v2.4.0 delivered the code, v2.4.1 ensures users can actually use it.
AP_DS_WAV_THRESHOLD – WAV playback mode threshold (from v2.3.5)AP_DS_HIDE_SUPPORT_PROMPT – Control startup message (new in v2.4.0)| Variable | Default | Description | Since |
|---|---|---|---|
AP_DS_WAV_THRESHOLD |
6 |
WAV threshold in seconds (≥ threshold = music mode with seek support) | v2.3.5 |
AP_DS_HIDE_SUPPORT_PROMPT |
not set | Set to 1 to hide the startup welcome message |
v2.4.0 |
No code changes required – all existing applications continue to work unchanged.
To start using new features:
# Before (v2.3.x)
aid = lib.play_from_file("song.mp3")
time.sleep(5)
lib.stop_audio(aid) # Abrupt stop
# After (v2.4.0) - Professional!
aid = lib.play_from_file("song.mp3")
time.sleep(5)
lib.fadeout_music(ms=3000) # Smooth exit over 3 seconds
# Install or upgrade to latest version
pip install --upgrade ap_ds
# Verify installation
python -c "import ap_ds; print(ap_ds.__version__)" # Should show 2.4.1
| Metric | Value |
|---|---|
| Package Size | Windows: 2.5MB / macOS: 3.36MB / Linux: depends on system SDL2 |
| Memory Growth | ~4MB after extensive testing |
| Python Support | 3.7+ (all versions) |
| Platform Support | Windows, macOS, Linux (x86_64, ARM64) |
| API Compatibility | 100% backward compatible with v2.3.x |
v2.4.0 transforms ap_ds from a "playback library" into a professional audio tool:
v2.4.1 ensures every user can fully leverage these features:
All while maintaining the core promise: lightweight, zero external Python dependencies, and true cross-platform compatibility.
{
'format': 'MP3', # File format
'duration': 240, # Duration in seconds
'sample_rate': 44100, # Sample rate in Hz
'channels': 2, # Number of channels
'bitrate': 320000 # Bitrate in bps
}
{
'path': '/Music/song.mp3', # File path
'duration': 240, # Duration in seconds
'bitrate': 320000, # Bitrate in bps
'channels': 2 # Number of channels
}
from ap_ds import get_audio_parser
parser = get_audio_parser()
metadata = parser.get_audio_metadata("song.mp3")
if metadata:
print(f"Format: {metadata['format']}")
print(f"Duration: {metadata['duration']} seconds")
print(f"Sample Rate: {metadata['sample_rate']}Hz")
print(f"Channels: {metadata['channels']}")
print(f"Bitrate: {metadata['bitrate']}bps")
# Pre-load audio files
effect = lib.new_aid("sound.wav")
music = lib.new_aid("track.flac")
# Play from memory (instant start)
lib.play_audio(effect)
# Volume control
lib.set_volume(effect, 80)
current = lib.get_volume(effect)
# Get duration for progress bar
duration = lib.get_audio_duration(effect)
print(f"Duration: {duration}s")
import json
class ListeningAnalyzer:
def analyze(self, dap_path):
with open(dap_path, 'r', encoding='utf-8') as f:
records = json.load(f)
total_seconds = sum(r['duration'] for r in records)
hours = total_seconds // 3600
bitrate_stats = {}
for r in records:
bitrate_stats[r['bitrate']] = bitrate_stats.get(r['bitrate'], 0) + 1
return {
"total_songs": len(records),
"total_hours": hours,
"bitrate_distribution": bitrate_stats
}
import platform
from ap_ds import AudioLibrary
class Player:
def __init__(self):
self.lib = AudioLibrary()
print(f"Running on {platform.system()}")
def play(self, path):
try:
aid = self.lib.play_from_file(path)
print(f"Playing: {path}")
return aid
except Exception as e:
print(f"Error: {e}")
return None
| Format | Playback | Duration Precision | Metadata |
|---|---|---|---|
| MP3 | ✅ Full | >98% | Sample Rate, Bitrate |
| FLAC | ✅ Full | 100% | All Metadata |
| OGG | ✅ Full | 99.99% | All Metadata |
| WAV | ✅ Full | 100% | All Metadata |
| Solution | Size | Ratio |
|---|---|---|
| ap_ds (Windows) | 2.5 MB | 1x |
| ap_ds (macOS) | 3.36 MB | 1.34x |
| FFmpeg-based | 160+ MB | 64x |
| Pygame + parsers | 50+ MB | 20x |
Breakdown:
Yes, absolutely. The license explicitly permits any commercial use, including integration into commercial products, cloud services, and SaaS platforms, completely free of charge. You must comply with the attribution requirements.
ap_ds focuses precisely on playback and parsing for the four most common formats, avoiding the bloat of editing/transcoding features. It's built on the efficient SDL2 C library and is meticulously optimized.
MP3 duration parsing is >98% accurate. This is due to the format's variable header complexities. For WAV and FLAC we guarantee 100% accuracy, and for OGG 99.99%.
Yes! ap_ds includes testing on Orange Pi 4 Pro and Raspberry Pi 5 (ARM64) running Ubuntu 22.04. Memory growth is minimal (~4MB after extensive testing).
Set the environment variable:
# Linux/macOS
export AP_DS_WAV_THRESHOLD=10
# Windows Command Prompt
set AP_DS_WAV_THRESHOLD=10
# Windows PowerShell
$env:AP_DS_WAV_THRESHOLD=10
Yes. It only activates when standard verification fails, only downloads two specific audio libraries, and those libraries have extremely limited capabilities. See the SSL Certificate Verification section for detailed analysis.
ap_ds/
├── player.py # Main player logic, platform abstraction
├── audio_parser.py # Metadata parsing
├── audio_info.py # Format-specific parsers
└── __init__.py # Package initialization
self._audio_cache = {} # path -> Mix_Chunk
self._music_cache = {} # path -> Mix_Music
self._channel_info = {} # channel ID -> playback info
self._aid_to_filepath = {} # AID -> path
self._dap_recordings = [] # List of record dicts
# Memory: ~150 bytes per record
# 10,000 records → ~1.5 MB RAM
# 10,000 records → ~2-3 MB JSON file
Milestone: Project birth, foundational functionality
Core Features:
Technical Characteristics:
Milestone: Introduction of modern audio management system
Major Improvements:
Technical Upgrades:
Milestone: Professional functionality expansion
New Features:
Optimization Improvements:
Milestone: Production environment stable release
Version Highlights:
Market Positioning: "2.5MB Windows Python Audio Solution"
Technical Specifications Size Analysis:
├── SDL2.dll: 2.1MB
├── SDL2_mixer.dll: 400KB
└── Python Code: 42KB
Comparison Advantages:
├── FFmpeg Solution: At least 160MB (64x larger!)
├── Pygame Solution: Bloated with incomplete features
└── ap_ds: 2.5MB perfect solution ✓
Milestone: From single-platform to cross-platform
Major New Features:
Complete macOS Support
Enhanced Automatic Dependency Management
Strengthened Platform Position Statement
Performance & Optimization Size Control Breakthrough:
Windows Version: 2.5MB
├── SDL2.dll: 2.1MB
├── SDL2_mixer.dll: 400KB
└── Python Code: 42KB
macOS Version: 3.36MB
├── SDL2.framework: 1.82MB
├── SDL2_mixer.framework: 1.54MB
└── Python Code: 42KB
Comparison with Traditional Solutions:
├── FFmpeg Solution: At least 160MB (47x larger than ap_ds!)
├── Pygame + Parser Libraries: Bloated with incomplete features
└── ap_ds: 3.36MB complete solution ✓
Loading Performance Optimization:
Technical Architecture Improvements - Cross-Platform Loading System:
def import_sdl2():
"""Intelligent SDL2 library loading (Windows/macOS)"""
if platform == "win32":
# Load .dll
elif platform == "darwin":
# Load .framework
else:
# Explicitly reject unsupported platforms
Enhanced Error Handling:
Documentation & Examples Update:
pip install ap_ds (fully automatic)pip install ap_ds (fully automatic, requires network download)Design Philosophy Reiteration:
Market Positioning Upgrade:
Milestone: From playback to memory, introducing audio playback history recording system
DAP (Dvs Audio Playlist) is a major functional extension of the ap_ds library, providing developers with a complete solution for audio playback history recording. This is not a traditional playlist manager, but a lightweight system focused on recording and memory.
Core Characteristics:
Intelligent Automatic Recording
play_from_file(), play_from_memory()Lightweight Design Philosophy
Standardized File Format
.ap-ds-dap ensures format recognitionNew API Details
DAP Recording Function List
_add_to_dap_recordings(file_path: str) -> None
# Automatically triggered via playback
lib.play_from_file("song.mp3") # Automatically recorded to DAP
# Log output: Recorded DAP file: song.mp3
save_dap_to_json(save_path: str) -> bool
.ap-ds-dapTrue: Save successfulFalse: Save failed (error logged)try:
success = lib.save_dap_to_json("history.ap-ds-dap")
except ValueError as e:
print(f"Format error: {e}") # Extension doesn't meet requirements
get_dap_recordings() -> List[Dict]
[
{
"path": "/music/song1.mp3",
"duration": 240,
"bitrate": 320000,
"channels": 2
}
]
clear_dap_recordings() -> None
Technical Architecture Design
Workflow:
User plays audio
↓
Calls play_from_file()
↓
Automatically calls _add_to_dap_recordings()
↓
Extracts metadata via get_audio_metadata_by_path()
↓
Creates standardized record
↓
Adds to _dap_recordings list
↓
Intelligent deduplication check
↓
Stores in memory
↓
User optionally calls save_dap_to_json()
↓
Extension validation → JSON serialization → File saving
Memory Management Design:
class AudioLibrary:
def __init__(self):
# DAP memory storage
self._dap_recordings = [] # List[Dict]
# Approximate memory usage per record:
# path: ~100 bytes
# metadata: ~50 bytes
# total: ~150 bytes/record
Performance Characteristics:
Milestone: Improved documentation and minor fixes
Changes:
Milestone: Extended Linux support with interactive setup
Major New Features:
Interactive Linux Support
Enhanced Cross-Platform Compatibility
Improved User Experience
Technical Implementation:
def import_sdl2():
"""Main function: Import SDL2 libraries with cross-platform support"""
platform = sys.platform
if platform == "win32":
# Windows - auto-download and load .dll
elif platform == "darwin":
# macOS - auto-download and load .framework
elif platform.startswith("linux"):
# Linux - interactive setup with options:
print("Linux SDL2 Library Loading")
print("Options:")
print("1. Use system-installed libraries (if available)")
print("2. Specify path to your compiled .so files")
print("3. Get compilation instructions")
# User interaction and library loading
Market Positioning Upgrade:
Performance & Optimization:
Backward Compatibility:
🚨 This is a critical update that fixes a major bug. Previous versions (2.2.0, 2.3.0, 2.3.1, 2.3.2) have been yanked from PyPI due to this issue. Please upgrade immediately.
Critical Fix:
Enhanced Stability & Integrity:
pip install ap_ds followed by functional playback and parsing—is now reliably fulfilled on all three major platforms.What This Means for You:
pip install --upgrade ap_ds now.Technical Summary:
This patch (2.3.2 → 2.3.3) is a PATCH-level version change under Semantic Versioning, signifying a backward-compatible bug fix that resolves incorrect behavior. The core API, features, and user experience remain unchanged and now operate reliably everywhere.
Maintainer's Note: We sincerely apologize for the disruption. Upholding stability and a professional standard for all users is our top priority. Version 2.3.3 represents that commitment.
🚀 This update revolutionizes Linux support with an intelligent, multi-layer import system that dramatically improves user experience.
Intelligent Linux Import System
Four-Layer Fallback Strategy: Implements a sophisticated, progressive library discovery system:
Package Manager Detection & Auto-Install:
apt-get and installs libsdl2-dev libsdl2_mixer-devdnf and installs SDL2-devel SDL2_mixer-develpacman and installs sdl2 sdl2_mixer-y/--noconfirm) for seamless setupConfiguration Persistence & Smart Memory:
AP_DS_SDL2_PATH, AP_DS_SDL2_MIXER_PATH)~/.config/ap_ds/sdl_paths.conf)Enhanced User Experience:
Technical Implementation Highlights:
def import_sdl2():
"""Intelligent multi-layer SDL2 import system"""
if platform.startswith("linux"):
# Layer 1: System library check
if find_system_libraries():
return load_from_system()
# Layer 2: User-configured paths
if check_user_config():
return load_from_user_config()
# Layer 3: Automatic package manager installation
if try_auto_install():
return load_from_newly_installed()
# Layer 4: Interactive guidance (only if all else fails)
return interactive_setup_and_save()
Platform-Specific Improvements:
Performance & Stability:
What This Means for You:
pip install ap_ds followed by automatic setup in most casesStability & Testing
Six-Dimension Test Coverage:
Library Loading & Initialization
Playback Testing
Seek Testing
Memory Pressure & Leak Detection
Metadata Parsing Accuracy
DAP System Validation
Embedded Platform Support
Tested Environments:
| Platform | SoC | Cores | RAM | OS | Audio Output |
|---|---|---|---|---|---|
| Orange Pi 4 Pro | Allwinner A733 | 2xA76 + 6xA55 @ 2.0GHz | 8GB LPDDR5 | Ubuntu 22.04 ARM64 | 3.5mm → TPA3116D2 @ 2×8Ω 5W |
| Raspberry Pi 5 | BCM2712 | 4xA76 @ 2.4GHz | 8GB LPDDR4X | Ubuntu 22.04 ARM64 | 3.5mm → TPA3116D2 @ 2×8Ω 5W |
Results:
Important Note: ap_ds is a wrapper library. Low-level concerns (power optimization, I2S/HDMI/ALSA output, fine-grained memory management) are handled by SDL2 and the operating system. Python's language nature limits fine resource control. We have tested and confirmed functionality; no embedded-specific optimizations are planned as they fall outside our scope.
Bug Fixes
WAV Playback Mode Selection
Fixed an issue where WAV files were incorrectly treated as sound effects, preventing seek operations.
New Logic:
AP_DS_WAV_THRESHOLD environment variableValidation:
WAV_THRESHOLD = int(os.environ.get('AP_DS_WAV_THRESHOLD', '6'))
if WAV_THRESHOLD >= 30: # Reset to default to prevent memory issues
WAV_THRESHOLD = 6
elif WAV_THRESHOLD < 0:
WAV_THRESHOLD = 6
Error Message Decision
Design Decision: Keep Existing Simple Error Format
Proposed Change Rejected: Structured error messages with causes and suggestions were considered but rejected.
Reasons:
Limited Help for Complex Errors
Target Users Are Developers
Maintenance Burden
raise RuntimeError(f"Failed to load: {file_path}")Final Decision: Maintain existing simple exception format with clear error messages.
SSL Certificate Issue: R12 Certificate Compatibility
Problem: On some Windows systems, R12 certificates cause verification failures during SDL2 download.
Solution Implemented:
def download_with_ssl(url):
try:
# First attempt: Standard SSL verification
return urllib.request.urlopen(url)
except (URLError, SSLError) as e:
# Fallback: Unverified context
ssl_context = ssl.create_default_context()
ssl_context.check_hostname = False
ssl_context.verify_mode = ssl.CERT_NONE
opener = urllib.request.build_opener(
urllib.request.HTTPSHandler(context=ssl_context)
)
urllib.request.install_opener(opener)
return urllib.request.urlopen(url)
Security Rationale:
This version updates the PyPi documentation, adding detailed license information and version history, and adding more examples.
✅ This version introduces professional audio transitions and significant internal engineering upgrades.
Fade In/Out Functions:
| Function | Description |
|---|---|
fadein_music(aid, loops=-1, ms=0) |
Fade in music over specified milliseconds |
fadein_music_pos(aid, loops=-1, ms=0, position=0.0) |
Fade in from specific position |
fadeout_music(ms=0) |
Fade out currently playing music |
is_music_playing() |
Check if music is currently playing |
is_music_paused() |
Check if music is paused |
get_music_fading() |
Get current fade state (fading in/out/none) |
Implementation Details:
# Fade in over 2 seconds
aid = lib.play_from_file("song.mp3")
lib.fadein_music(aid, loops=-1, ms=2000)
# Fade in from 30-second mark
lib.fadein_music_pos(aid, loops=-1, ms=1500, position=30.0)
# Fade out over 3 seconds
lib.fadeout_music(ms=3000)
# Check states
if lib.is_music_playing():
print("Music is playing")
fade_state = lib.get_music_fading() # Returns MIX_NO_FADING, MIX_FADING_OUT, MIX_FADING_IN
Underlying SDL2 Functions:
Mix_FadeInMusic() - Basic fade inMix_FadeInMusicPos() - Positioned fade in Mix_FadeOutMusic() - Fade outMix_PlayingMusic() - Play state checkMix_PausedMusic() - Pause state checkMix_FadingMusic() - Fade state query1. Smart Welcome Message
The startup banner is now cleaner and user-controllable:
# Default behavior (shows once)
import ap_ds # Prints: AP_DS © - Audio Library By DVS v2.4.0 | https://www.apds.top
# Silence it with environment variable
import os
os.environ['AP_DS_HIDE_SUPPORT_PROMPT'] = '1'
import ap_ds # No output
2. Centralized Version Management
Version is now defined once in setup.py and automatically generates _version.py:
# setup.py
VERSION = "2.4.0"
def write_version_file():
version_file_path = os.path.join("ap_ds", "_version.py")
with open(version_file_path, "w", encoding="utf-8") as f:
f.write(f'__version__ = "{VERSION}"\n')
3. Robust Import System
Two-layer fallback ensures compatibility across all Python environments:
try:
from ._version import __version__
except ImportError:
try:
from _version import __version__
except ImportError:
__version__ = "unknown"
# Same pattern for core modules
try:
from .player import *
except ImportError:
from player import *
4. Unified Project URL
All project references now point to the central hub: https://www.apds.top
| Function | Parameters | Return | Description |
|---|---|---|---|
fadein_music |
aid: int, loops: int = -1, ms: int = 0 |
None |
Fade in audio instance |
fadein_music_pos |
aid: int, loops: int = -1, ms: int = 0, position: float = 0.0 |
None |
Fade in from position |
fadeout_music |
ms: int = 0 |
None |
Fade out current music |
is_music_playing |
() |
bool |
Check playing state |
is_music_paused |
() |
bool |
Check paused state |
get_music_fading |
() |
int |
Get fade state (0=no fade, 1=fade out, 2=fade in) |
| Variable | Default | Description |
|---|---|---|
AP_DS_WAV_THRESHOLD |
6 |
WAV threshold in seconds (from v2.3.5) |
AP_DS_HIDE_SUPPORT_PROMPT |
not set | Set to 1 to hide startup message |
No migration needed. Simply upgrade and enjoy the new features:
pip install --upgrade ap_ds
To use the new fade functions in existing code:
# Before (v2.3.x)
aid = lib.play_from_file("song.mp3")
time.sleep(5)
lib.stop_audio(aid)
# After (v2.4.0) - Professional transitions!
aid = lib.play_from_file("song.mp3")
lib.fadeout_music(ms=3000) # Smooth exit
v2.4.0 transforms ap_ds from a "playback library" into a professional audio tool with:
All while maintaining the core promise: lightweight, zero external Python dependencies, and cross-platform compatibility.
This version updates the PyPI documentation to fully reflect the new features introduced in v2.4.0, including detailed API descriptions, usage examples, and environment variable documentation.
Changes:
AP_DS_HIDE_SUPPORT_PROMPT environment variableNote: This release contains no code changes from v2.4.0—only documentation improvements.
ap_ds is built on a simple philosophy: focus on playback and parsing, stay lightweight, and let developers build great applications.
We welcome feedback, bug reports, and contributions. For questions or issues, please reach out through the official channels.
Thank you for using ap_ds!
For detailed information, please refer to: AP_DS_LICENSE.MD or AP_DS_LICENSE_v2.0_ZHCN.MD
For instructions, please refer to: AP_DS_GUIDE_v2.0_ZHCN.MD or AP_DS_GUIDE_v2.0_EN.MD
Thank you.
Q: Can a company integrate it in commercial products?
Q: Can I modify and redistribute it?
Q: Do I have to open‑source my modifications?
Q: Do I need to pay for cloud service usage?
Q: What if I get sued for patent infringement?
Q: Why such strict brand protection?
me@dvsyun.top or dvs6666@163.com · response within 7 working days
GitHub Issues · docs at official site · emergency email
Website: https://www.apds.top (root domain)
PyPI: https://pypi.org/project/ap_ds/
Developer: Dvs (DvsXT)