GUI Applications

Walrio includes several graphical user interface applications that provide easy-to-use interfaces for music playback and management. These applications are built using modern GUI frameworks and provide intuitive controls for various Walrio features.

Overview

The GUI applications are designed to be:

  • User-friendly: Intuitive interfaces suitable for all user levels

  • Modular: Each GUI serves a specific purpose or workflow

  • Integrated: Built on top of Walrio’s core modules and CLI tools

  • Cross-platform: Compatible with Windows, macOS, and Linux

Available GUI Applications:

  • Walrio Lite - Simple Music Player: Walrio Lite - Simple Music Player

  • Walrio Main GUI: Walrio Music Player GUI

Detailed Documentation

Walrio Lite - Simple Music Player

Location: /home/runner/work/Walrio/Walrio/GUI/walrio_lite.py

Walrio Lite - Simple Music Player

Dependencies:

  • PySide6

Classes and Methods:

SimplePlayerWorker

Worker thread for running simple audio playback.

Signals:

  • position_updated

  • playback_finished

  • error

Key Methods:

  • run() Run the simple audio player in daemon mode.

  • pause() Pause the playback using daemon command.

  • resume() Resume the playback using daemon command.

  • stop() Stop the playback using daemon command.

  • set_volume() Set the playback volume using daemon socket command.

SimpleMusicPlayer

Simple music player focused entirely on playback controls.

Key Methods:

  • setup_ui() Setup the simple music player user interface.

  • setup_timer() Setup timer for updating UI (reduced frequency since position comes from worker).

  • open_file() Open an audio file for simple playback.

  • toggle_play_pause() Toggle between play, pause, and resume for simple playback.

  • start_playback() Start simple audio playback.

  • pause_playback() Pause simple audio playback using CLI command.

  • resume_playback() Resume simple audio playback using CLI command.

  • stop_playback() Stop simple audio playback.

  • on_volume_change()

  • on_seek_start() Handle when user starts seeking in simple player.

  • on_seek_end() Handle when user finishes seeking in simple player.

  • on_position_updated()

  • update_ui() Update UI elements for simple player (called by timer).

  • format_time()

  • on_playback_finished() Handle when simple playback finishes naturally.

  • on_playback_error()

  • show_message()

  • closeEvent()

  • main() Main entry point for Walrio Lite - Simple Music Player.

Usage:

python /home/runner/work/Walrio/Walrio/GUI/walrio_lite.py

Note

This is a graphical application. Ensure you have a display environment available and the required GUI dependencies installed.

Walrio Main GUI

Location: /home/runner/work/Walrio/Walrio/GUI/walrio_main.py

Walrio Music Player GUI

Dependencies:

  • PySide6

Classes and Methods:

QueueWorker

Worker thread for queue operations like metadata extraction.

Signals:

  • file_processed

  • all_files_processed

  • error

Key Methods:

  • run() Process files in background thread.

  • _get_file_metadata()

  • _parse_duration()

  • stop() Stop the worker thread.

PlayerWorker

Worker thread for handling audio playback operations with event-based communication.

Signals:

  • position_updated

  • playback_finished

  • song_starting

  • error

Key Methods:

  • run() Run the audio player with event-based communication.

  • _send_socket_command() Send a command to the player daemon via socket.

  • pause()

  • resume()

  • stop() Stop the playback using daemon socket command.

  • _send_socket_command() Send a command to the player daemon via socket.

  • seek()

  • set_volume()

  • get_position()

  • send_command()

  • _connect_to_daemon_events_with_retry() Connect to daemon events with retry logic for timing issues.

  • _connect_to_daemon_events()

  • _check_daemon_events() Check for events from the daemon.

  • _process_daemon_event()

  • _cleanup_event_socket() Clean up the event socket connection.

  • _start_event_listener_thread() Start a dedicated thread for listening to daemon events.

  • _event_listener_loop() Dedicated event listener loop running in separate thread.

  • play_new_song()

  • _start_audio_process() Start the persistent daemon process.

WalrioMusicPlayer

Walrio music player with full playback controls.

Key Methods:

  • _update_queue_manager()

  • setup_ui() Setup the user interface.

  • setup_timer() Setup timer for updating UI (reduced frequency since position comes from worker).

  • add_files_to_queue() Add files to the queue using background thread.

  • on_file_processed()

  • on_all_files_processed() Handle when all files have been processed.

  • on_queue_error()

  • clear_queue() Clear all songs from the queue.

  • remove_selected_from_queue() Remove selected song from the queue.

  • on_queue_reordered()

  • on_queue_item_clicked() Handle clicking on a queue item to select it (single-click only selects, does not play).

  • on_queue_item_double_clicked() Handle double-clicking on a queue item to immediately play it.

  • load_song_from_queue() Load a song from the queue by index.

  • get_file_duration() Get the duration of an audio file.

  • get_file_metadata() Get metadata for an audio file including artist, title, album, and duration.

  • update_queue_display() Update the queue table widget display (Strawberry-style optimized).

  • update_queue_highlighting() Update only the highlighting of the currently playing song (lightweight update).

  • show_column_context_menu() Show context menu for column visibility on header right-click.

  • toggle_column_visibility() Toggle the visibility of a table column.

  • toggle_play_pause() Toggle between play, pause, and resume.

  • toggle_loop() Toggle repeat mode between ‘off’ and ‘track’ (queue-based approach).

  • restart_with_loop()

  • start_playback() Start audio playback with queue-based loop support.

  • _set_daemon_loop_mode() Set the daemon’s loop mode to ‘none’ for queue-controlled progression.

  • pause_playback() Pause audio playback using CLI command.

  • resume_playback() Resume audio playback using CLI command.

  • stop_playback() Stop audio playback.

  • on_volume_change()

  • slider_mouse_press_event()

  • on_slider_value_changed()

  • on_seek_start() Handle when user starts seeking.

  • on_seek_end() Handle when user finishes seeking.

  • on_position_updated()

  • update_ui() Update UI elements (called by timer).

  • format_time()

  • on_playback_finished() Handle when playback finishes - use queue system for completion logic.

  • next_track() Skip to the next track in the queue.

  • previous_track() Skip to the previous track in the queue.

  • on_playback_error()

  • show_message()

  • closeEvent()

  • main() Main entry point for Walrio.

Usage:

python /home/runner/work/Walrio/Walrio/GUI/walrio_main.py

Note

This is a graphical application. Ensure you have a display environment available and the required GUI dependencies installed.

Installation Requirements

To run the GUI applications, you need:

Core Dependencies:

pip install PySide6

System Requirements:

  • Python 3.8+ - Required Python version

  • Display Environment - GUI applications require:

    • Linux: X11 or Wayland display server

    • macOS: Native Cocoa support (built-in)

    • Windows: Native Windows desktop (built-in)

Audio Dependencies:

The GUI applications use Walrio’s audio modules, which may require:

  • FFmpeg - For audio format support and metadata extraction

  • GStreamer - For advanced audio playback features

Installation on Different Platforms:

# Ubuntu/Debian
sudo apt install python3-pyside6 ffmpeg gstreamer1.0-plugins-base

# macOS (with Homebrew)
brew install python-tk ffmpeg
pip install PySide6

# Windows
pip install PySide6
# Download FFmpeg from https://ffmpeg.org/download.html

Troubleshooting

Common Issues:

  • “No module named ‘PySide6’”: Install PySide6 with pip install PySide6

  • “Cannot connect to display”: Ensure you have a GUI environment running

  • Audio playback issues: Verify FFmpeg is installed and accessible

Getting Help:

For more information about the underlying modules used by these GUI applications, see:

Development

These GUI applications are built using:

  • PySide6/Qt6 - Cross-platform GUI framework

  • Threading - For responsive user interfaces during audio operations

  • Walrio Modules - Integration with core audio processing capabilities

For extending or modifying the GUI applications, refer to the source code and the detailed class documentation above.