Skip to content

PHASE2_IMPLEMENTATION.md

Latest commit

 

History

History
296 lines (237 loc) · 7.87 KB

PHASE2_IMPLEMENTATION.md

File metadata and controls

296 lines (237 loc) · 7.87 KB

Phase 2: Playback Essentials - Implementation Details

Overview

Phase 2 adds advanced playback controls and comprehensive playlist management to OneAmp, bringing it closer to Winamp Modern feature parity.

Features Implemented

1. Advanced Playlist Management

1.1 Playlist Structure (playlist.rs)

  • PlaylistEntry: Represents individual tracks with metadata

    • Path, title, artist, album, duration
    • Display name fallback to filename

  • Playlist: Full-featured playlist with:

    • Add/remove entries
    • Current index tracking
    • Shuffle mode with reproducible seeds
    • Sort by: Title, Artist, Album, Path, Duration
    • Search functionality (title, artist, album)
    • Next/Previous track navigation (shuffle-aware)

  • PlayQueue: Temporary play queue

    • Enqueue at end or front (play next)
    • FIFO dequeue
    • Independent from main playlist

1.2 Playlist Persistence

  • M3U Format Support:

    • Save: #EXTM3U format with metadata
    • Load: Parse EXTINF tags for duration/title

  • PLS Format Support:

    • Save: Standard PLS format with File/Title/Length
    • Load: Parse numbered entries

2. Shuffle Mode

2.1 Implementation Details

  • Reproducible Shuffle: Uses seed-based Fisher-Yates algorithm
  • Seed Management: Configurable seed for consistent shuffle order
  • Integration: Works with repeat modes and playlist navigation
  • Regeneration: Auto-regenerates on playlist changes

2.2 Audio Engine Integration

  • New commands: SetShuffle(bool), SetShuffleSeed(u64)
  • New events: ShuffleUpdated(bool)
  • State persistence in AudioEngineState

3. Playback Speed Control

3.1 Speed Range

  • Range: 0.5x to 2.0x
  • Default: 1.0x (normal speed)
  • Clamping: Automatic clamping to valid range

3.2 Implementation Notes

  • Command: SetPlaybackSpeed(f32)
  • Event: PlaybackSpeedUpdated(f32)
  • Note: Actual audio resampling not yet implemented
    • Placeholder for future DSP integration
    • Will require audio processing pipeline enhancement

4. Recent Files History

4.1 Features (recent_files.rs)

  • Tracking: Last 20 files by default (configurable)
  • Metadata: Last played timestamp, play count
  • Persistence: JSON serialization
  • Management: Add, remove, clear operations
  • Smart Updates: Moves existing files to front, increments play count

4.2 Usage

let mut recent = RecentFiles::new();
recent.add_file(PathBuf::from("song.mp3"));
recent.save("recent.json")?;

5. Configuration Enhancements

5.1 New PlaybackConfig Fields

pub struct PlaybackConfig {
    pub volume: f32,
    pub muted: bool,
    pub repeat_mode: RepeatModeConfig,
    pub playback_speed: f32,        // NEW
    pub shuffle_enabled: bool,       // NEW
    pub shuffle_seed: u64,           // NEW
}

5.2 Persistence

  • All settings saved to config file
  • Restored on application restart
  • Backward compatible with Phase 1 configs

Architecture Decisions

1. UI-Agnostic Core

All playlist and playback logic is in oneamp-core, making it:

  • Reusable across different UIs
  • Compatible with .wsz theme system
  • Testable independently
  • Easy to integrate with future frontends

2. Event-Driven Design

All state changes emit events:

  • ShuffleUpdated(bool)
  • PlaybackSpeedUpdated(f32)
  • Enables reactive UI updates
  • Supports theme system integration

3. Separation of Concerns

  • Core: Playlist logic, audio commands
  • Desktop: UI integration, configuration
  • Audio Thread: Playback state management

Integration with .wsz Theme System

Design Considerations

  1. State Exposure: All playback state available via events
  2. Command Interface: Theme UI can send any AudioCommand
  3. Metadata Access: Playlist entries include all display metadata
  4. Flexible Layout: Core doesn't dictate UI structure

Theme Integration Points

// Themes can:
// 1. Display playlist
for entry in playlist.entries() {
    render_playlist_item(entry);
}

// 2. Control shuffle
engine.send_command(AudioCommand::SetShuffle(true));

// 3. Show playback speed
match event {
    AudioEvent::PlaybackSpeedUpdated(speed) => {
        update_speed_display(speed);
    }
}

// 4. Access recent files
let recent = RecentFiles::load("recent.json")?;
for file in recent.files() {
    render_recent_item(file);
}

Testing

Unit Tests Included

  • ✅ Playlist creation and manipulation
  • ✅ Shuffle mode reproducibility
  • ✅ Next/Previous navigation
  • ✅ Search functionality
  • ✅ Sort operations
  • ✅ Queue management
  • ✅ Recent files tracking
  • ✅ M3U/PLS save/load

Integration Testing Needed

  • Full playback with shuffle
  • Playlist persistence across restarts
  • Speed control with actual audio
  • Theme system integration

Future Enhancements (Phase 3+)

Immediate Next Steps

  1. Crossfade: Smooth transitions between tracks
  2. Gapless Playback: Eliminate silence between tracks
  3. Advanced Seek: Frame-accurate seeking

Audio Processing

  1. Speed Implementation: Actual audio resampling
  2. Pitch Preservation: Maintain pitch at different speeds
  3. Quality Settings: Configurable resampling quality

Playlist Features

  1. Smart Playlists: Dynamic filtering
  2. Playlist Groups: Organize multiple playlists
  3. Auto-Playlists: Based on metadata criteria

API Reference

New Commands

AudioCommand::SetPlaybackSpeed(f32)  // 0.5 - 2.0
AudioCommand::SetShuffle(bool)       // Enable/disable
AudioCommand::SetShuffleSeed(u64)    // Set seed

New Events

AudioEvent::PlaybackSpeedUpdated(f32)
AudioEvent::ShuffleUpdated(bool)

New Types

Playlist                  // Main playlist
PlaylistEntry            // Single track
PlayQueue                // Temporary queue
SortOrder                // Sort criteria
RecentFiles              // History manager
RecentFile               // History entry

Migration Guide

From Phase 1

  1. Update oneamp-core dependency
  2. Add new config fields (auto-defaults)
  3. Handle new events in UI
  4. Optional: Integrate playlist UI

Configuration

Old configs are automatically upgraded:

{
  "playback": {
    "volume": 0.8,
    "muted": false,
    "repeat_mode": "Off"
    // New fields auto-default
  }
}

Performance Considerations

Playlist Operations

  • Add/Remove: O(1) amortized
  • Search: O(n) linear scan
  • Sort: O(n log n) standard sort
  • Shuffle: O(n) Fisher-Yates

Memory Usage

  • Playlist: ~200 bytes per entry
  • Recent Files: ~150 bytes per entry
  • Shuffle Order: 8 bytes per entry

Optimization Opportunities

  1. Lazy metadata loading
  2. Playlist indexing for search
  3. Incremental shuffle updates

Known Limitations

  1. Playback Speed: Command exists but audio resampling not implemented
  2. Large Playlists: No virtualization yet (>10k entries may be slow)
  3. Metadata: Not automatically extracted on add (requires manual update)
  4. Crossfade: Not implemented in Phase 2

Compatibility

Winamp Parity Status

  • ✅ Shuffle mode
  • ✅ Playlist management
  • ✅ M3U/PLS support
  • ✅ Recent files
  • ⚠️ Playback speed (partial)
  • ❌ Crossfade (Phase 3)
  • ❌ Gapless (Phase 3)

File Format Support

  • ✅ M3U (Extended)
  • ✅ PLS
  • ❌ M3U8 (UTF-8) - Future
  • ❌ XSPF - Future
  • ❌ WPL - Future

Contributing

Adding New Features

  1. Add to oneamp-core first
  2. Emit events for state changes
  3. Add unit tests
  4. Update this documentation
  5. Consider theme integration

Code Style

  • Follow existing patterns
  • Document public APIs
  • Include examples in docs
  • Add tests for new functionality

Conclusion

Phase 2 establishes a solid foundation for advanced playback features while maintaining compatibility with the upcoming .wsz theme system. The architecture is designed to be extensible and theme-agnostic, allowing for flexible UI implementations.

Next Phase: Audio Processing (EQ, Effects, Gapless)