`36a9617`

Add animated GIF support with daemon integration

- GIF decoder with frame-by-frame access and timing
- Double-buffered X11 rendering for smooth animation
- Animation event loop integrated into daemon
- CLI --animate flag and --max-fps option
- X11 error handling improvements

Authored by mfwolffe <wolffemf@dukes.jmu.edu> 4 months ago

SHA: 36a9617b3491c59e4d0ffbdfe592ff5497bb54eb
Parents: 92945ac
Tree: 19cd850

10 changed files

Status	File	+	-
A	`garbg/src/daemon/animation_loop.rs`	250	0
M	`garbg/src/daemon/mod.rs`	2	0
M	`garbg/src/daemon/state.rs`	205	10
M	`garbg/src/ipc/protocol.rs`	11	0
M	`garbg/src/main.rs`	107	10
A	`garbg/src/media/gif.rs`	192	0
M	`garbg/src/media/mod.rs`	2	0
A	`garbg/src/x11/animation.rs`	201	0
M	`garbg/src/x11/connection.rs`	49	2
M	`garbg/src/x11/mod.rs`	3	1

garbg/src/daemon/animation_loop.rsadded

 +//! Animation playback loop for GIF wallpapers
 +//!
 +//! Manages frame timing and rendering for animated wallpapers.
++
 +use anyhow::Result;
 +use std::sync::atomic::{AtomicBool, Ordering};
 +use std::sync::Arc;
 +use std::time::{Duration, Instant};
++
 +use crate::config::ScaleMode;
 +use crate::media::{scale_image, AnimatedGif};
 +use crate::x11::{AnimationRenderer, Connection};
++
 +/// Configuration for the animation loop
 +#[derive(Debug, Clone)]
 +pub struct AnimationConfig {
 +    /// Maximum FPS (0 = unlimited, capped at source FPS)
 +    pub max_fps: u32,
 +    /// Whether to skip frames when running behind
 +    pub adaptive_skip: bool,
 +    /// Scaling mode for frames
 +    pub scale_mode: ScaleMode,
 +}
++
 +impl Default for AnimationConfig {
 +    fn default() -> Self {
 +        Self {
 +            max_fps: 60,
 +            adaptive_skip: true,
 +            scale_mode: ScaleMode::Fill,
 +        }
 +    }
 +}
++
 +/// Animation loop state
 +pub struct AnimationLoop {
 +    /// The animated GIF being played
 +    gif: AnimatedGif,
 +    /// X11 animation renderer
 +    renderer: AnimationRenderer,
 +    /// Pre-scaled frames (cached)
 +    scaled_frames: Vec<image::RgbaImage>,
 +    /// Configuration
 +    config: AnimationConfig,
 +    /// Whether the animation is paused
 +    paused: Arc<AtomicBool>,
 +    /// Whether to stop the animation
 +    stop: Arc<AtomicBool>,
 +}
++
 +impl AnimationLoop {
 +    /// Create a new animation loop for a GIF
 +    pub fn new(
 +        gif: AnimatedGif,
 +        conn: &Connection,
 +        config: AnimationConfig,
 +    ) -> Result<Self> {
 +        let renderer = AnimationRenderer::new(conn)?;
 +        let (screen_width, screen_height) = renderer.dimensions();
++
 +        // Pre-scale all frames
 +        let scaled_frames: Vec<image::RgbaImage> = gif
 +            .frames()
 +            .iter()
 +            .map(|frame| {
 +                scale_image(
 +                    &frame.image,
 +                    screen_width as u32,
 +                    screen_height as u32,
 +                    config.scale_mode,
 +                )
 +            })
 +            .collect();
++
 +        Ok(Self {
 +            gif,
 +            renderer,
 +            scaled_frames,
 +            config,
 +            paused: Arc::new(AtomicBool::new(false)),
 +            stop: Arc::new(AtomicBool::new(false)),
 +        })
 +    }
++
 +    /// Load a GIF from a file and create an animation loop
 +    pub fn from_file(
 +        path: &str,
 +        conn: &Connection,
 +        config: AnimationConfig,
 +    ) -> Result<Self> {
 +        let gif = AnimatedGif::load(path)?;
 +        Self::new(gif, conn, config)
 +    }
++
 +    /// Get a handle to pause/resume the animation
 +    pub fn pause_handle(&self) -> Arc<AtomicBool> {
 +        Arc::clone(&self.paused)
 +    }
++
 +    /// Get a handle to stop the animation
 +    pub fn stop_handle(&self) -> Arc<AtomicBool> {
 +        Arc::clone(&self.stop)
 +    }
++
 +    /// Run the animation loop (blocking)
 +    ///
 +    /// This will loop forever until `stop` is set to true.
 +    pub fn run(&mut self, conn: &mut Connection) -> Result<()> {
 +        if self.scaled_frames.is_empty() {
 +            anyhow::bail!("No frames to display");
 +        }
++
 +        // Calculate minimum frame duration based on max_fps
 +        let min_frame_duration = if self.config.max_fps > 0 {
 +            Duration::from_secs_f64(1.0 / self.config.max_fps as f64)
 +        } else {
 +            Duration::ZERO
 +        };
++
 +        let mut frame_index = 0;
 +        let mut next_frame_time = Instant::now();
 +        let mut frames_skipped = 0u64;
++
 +        tracing::info!(
 +            "Starting animation: {} frames, {:.1} FPS avg",
 +            self.scaled_frames.len(),
 +            self.gif.average_fps()
 +        );
++
 +        loop {
 +            // Check for stop signal
 +            if self.stop.load(Ordering::Relaxed) {
 +                tracing::info!("Animation stopped");
 +                break;
 +            }
++
 +            // Handle pause
 +            if self.paused.load(Ordering::Relaxed) {
 +                std::thread::sleep(Duration::from_millis(50));
 +                next_frame_time = Instant::now();
 +                continue;
 +            }
++
 +            let now = Instant::now();
++
 +            // Check if we're behind schedule
 +            if self.config.adaptive_skip && now > next_frame_time {
 +                let behind = now - next_frame_time;
++
 +                // Skip frames if we're more than one frame behind
 +                while next_frame_time < now {
 +                    let frame_delay = self.gif.frames()[frame_index].delay;
 +                    next_frame_time += frame_delay.max(min_frame_duration);
 +                    frame_index = (frame_index + 1) % self.scaled_frames.len();
 +                    frames_skipped += 1;
 +                }
++
 +                if frames_skipped > 0 && frames_skipped % 100 == 0 {
 +                    tracing::debug!(
 +                        "Skipped {} frames total ({}ms behind)",
 +                        frames_skipped,
 +                        behind.as_millis()
 +                    );
 +                }
 +            }
++
 +            // Render current frame
 +            let scaled_frame = &self.scaled_frames[frame_index];
 +            self.renderer.render_and_present(conn, scaled_frame)?;
++
 +            // Get delay for current frame
 +            let frame_delay = self.gif.frames()[frame_index].delay;
 +            let actual_delay = frame_delay.max(min_frame_duration);
++
 +            // Advance to next frame
 +            frame_index = (frame_index + 1) % self.scaled_frames.len();
 +            next_frame_time += actual_delay;
++
 +            // Sleep until next frame
 +            let sleep_time = next_frame_time.saturating_duration_since(Instant::now());
 +            if !sleep_time.is_zero() {
 +                std::thread::sleep(sleep_time);
 +            }
 +        }
++
 +        Ok(())
 +    }
++
 +    /// Run a single iteration (non-blocking, for integration with async loops)
 +    ///
 +    /// Returns the duration to wait before the next frame.
 +    pub fn tick(&mut self, conn: &mut Connection) -> Result<Duration> {
 +        if self.scaled_frames.is_empty() {
 +            return Ok(Duration::from_millis(100));
 +        }
++
 +        if self.paused.load(Ordering::Relaxed) {
 +            return Ok(Duration::from_millis(50));
 +        }
++
 +        let frame_index = self.gif.current_index();
 +        let scaled_frame = &self.scaled_frames[frame_index];
++
 +        // Render current frame
 +        self.renderer.render_and_present(conn, scaled_frame)?;
++
 +        // Get delay for current frame
 +        let delay = self.gif.current_frame().delay;
++
 +        // Advance to next frame
 +        self.gif.advance();
++
 +        // Cap at max_fps
 +        let min_delay = if self.config.max_fps > 0 {
 +            Duration::from_secs_f64(1.0 / self.config.max_fps as f64)
 +        } else {
 +            Duration::ZERO
 +        };
++
 +        Ok(delay.max(min_delay))
 +    }
++
 +    /// Get animation info
 +    pub fn info(&self) -> AnimationInfo {
 +        AnimationInfo {
 +            frame_count: self.gif.frame_count(),
 +            current_frame: self.gif.current_index(),
 +            total_duration: self.gif.total_duration,
 +            average_fps: self.gif.average_fps(),
 +            dimensions: self.gif.dimensions(),
 +            paused: self.paused.load(Ordering::Relaxed),
 +        }
 +    }
++
 +    /// Clean up resources
 +    pub fn destroy(self, conn: &Connection) {
 +        self.renderer.destroy(conn);
 +    }
 +}
++
 +/// Information about the current animation
 +#[derive(Debug, Clone)]
 +pub struct AnimationInfo {
 +    pub frame_count: usize,
 +    pub current_frame: usize,
 +    pub total_duration: Duration,
 +    pub average_fps: f64,
 +    pub dimensions: (u32, u32),
 +    pub paused: bool,
 +}

garbg/src/daemon/mod.rsmodified

  //! Runs as a background service managing wallpapers.
  mod state;
 +mod animation_loop;
  pub use state::{Daemon, DaemonState};
 +pub use animation_loop::{AnimationLoop, AnimationConfig, AnimationInfo};

garbg/src/daemon/state.rsmodified

  //! Daemon state management
 -use anyhow::Result;
 +use anyhow::{Context, Result};
  use std::collections::HashMap;
  use std::time::Duration;
  use tokio::net::UnixStream;
  use crate::config::{Config, ScaleMode};
  use crate::ipc::{Command, GarEvent, GarIpcClient, IpcServer, Response};
  use crate::ipc::server::IpcClient;
 -use crate::media::{scale_image, ImageLoader};
 +use crate::media::{scale_image, AnimatedGif, ImageLoader};
  use crate::state::{detect_source_type, PlaylistState};
 -use crate::x11::Connection;
 +use crate::x11::{AnimationRenderer, Connection};
  /// Current wallpaper state for a monitor
  #[derive(Debug, Clone)]
+     }
+ }
 +/// Active animation state
 +pub struct ActiveAnimation {
 +    /// The animated GIF data
 +    gif: AnimatedGif,
 +    /// Pre-scaled frames for quick rendering
 +    scaled_frames: Vec<image::RgbaImage>,
 +    /// Animation renderer (double-buffered)
 +    renderer: AnimationRenderer,
 +    /// Current frame index
 +    current_frame: usize,
 +    /// Max FPS
 +    max_fps: u32,
 +    /// Scale mode
 +    scale_mode: ScaleMode,
 +    /// Source URI (for status)
 +    source: String,
 +}
++
 +impl ActiveAnimation {
 +    /// Get the delay for the current frame
 +    fn current_delay(&self) -> Duration {
 +        let frame_delay = self.gif.frames()[self.current_frame].delay;
 +        let min_delay = if self.max_fps > 0 {
 +            Duration::from_secs_f64(1.0 / self.max_fps as f64)
 +        } else {
 +            Duration::ZERO
 +        };
 +        frame_delay.max(min_delay)
 +    }
++
 +    /// Advance to next frame, returning true if looped
 +    fn advance(&mut self) -> bool {
 +        self.current_frame += 1;
 +        if self.current_frame >= self.scaled_frames.len() {
 +            self.current_frame = 0;
 +            true
 +        } else {
 +            false
 +        }
 +    }
 +}
++
  /// Main daemon struct
  pub struct Daemon {
      /// X11 connection
      /// Daemon state
      state: DaemonState,
++
 +    /// Current animation (if playing)
 +    animation: Option<ActiveAnimation>,
+ }
  impl Daemon {
      /// Create a new daemon
 +    ///
 +    /// Establishes X11 connection and initializes state.
 +    /// Fails early with helpful error messages if X11 is unavailable.
      pub fn new(config: Config) -> Result<Self> {
 -        let conn = Connection::new()?;
 +        let conn = Connection::new()
 +            .context("Failed to initialize X11 connection for daemon")?;
++
 +        // Verify connection is working
 +        if !conn.is_alive() {
 +            anyhow::bail!("X11 connection established but not responding");
 +        }
++
 +        let (width, height) = conn.screen_dimensions();
 +        tracing::info!("X11 connection established (screen: {}x{})", width, height);
++
          let state = DaemonState::new(config);
 -        Ok(Self { conn, state })
 +        Ok(Self {
 +            conn,
 +            state,
 +            animation: None,
 +        })
+     }
      /// Run the daemon event loop
              tracing::info!("Slideshow enabled: {:?} interval", interval);
+         }
 +        // Track next animation frame time
 +        let mut next_animation_frame: Option<tokio::time::Instant> = None;
++
          // Main event loop
          loop {
              tokio::select! {
                              // Update slideshow timer if interval changed
                              next_slideshow = self.state.slideshow_interval
                                  .map(|d| tokio::time::Instant::now() + d);
 +                            // Update animation timer if animation started
 +                            if self.animation.is_some() && next_animation_frame.is_none() {
 +                                next_animation_frame = Some(tokio::time::Instant::now());
 +                            } else if self.animation.is_none() {
 +                                next_animation_frame = None;
 +                            }
+                         }
                          Err(e) => {
                              tracing::warn!("Accept error: {}", e);
+                     }
+                 }
 -                // Slideshow timer (only if enabled and not paused)
 +                // Animation frame timer (highest priority when active)
                  _ = async {
 -                    match (next_slideshow, self.state.paused) {
 -                        (Some(deadline), false) => {
 +                    match (next_animation_frame, self.state.paused, &self.animation) {
 +                        (Some(deadline), false, Some(_)) => {
 +                            tokio::time::sleep_until(deadline).await;
 +                        }
 +                        _ => {
 +                            std::future::pending::<()>().await;
 +                        }
 +                    }
 +                } => {
 +                    if let Err(e) = self.render_animation_frame() {
 +                        tracing::warn!("Animation frame render failed: {}", e);
 +                        // Stop animation on error
 +                        self.animation = None;
 +                        next_animation_frame = None;
 +                    } else if let Some(ref anim) = self.animation {
 +                        // Schedule next frame
 +                        let delay = anim.current_delay();
 +                        next_animation_frame = Some(tokio::time::Instant::now() + delay);
 +                    }
 +                }
++
 +                // Slideshow timer (only if enabled, not paused, and no animation)
 +                _ = async {
 +                    match (next_slideshow, self.state.paused, &self.animation) {
 +                        (Some(deadline), false, None) => {
                              tokio::time::sleep_until(deadline).await;
+                         }
                          _ => {
+         }
+     }
 +    /// Render the next animation frame
 +    fn render_animation_frame(&mut self) -> Result<()> {
 +        let anim = self.animation.as_mut()
 +            .ok_or_else(|| anyhow::anyhow!("No active animation"))?;
++
 +        // Render current frame
 +        let frame = &anim.scaled_frames[anim.current_frame];
 +        anim.renderer.render_and_present(&mut self.conn, frame)?;
++
 +        // Advance to next frame
 +        anim.advance();
++
 +        Ok(())
 +    }
++
      /// Handle a single client connection
      async fn handle_client(&mut self, stream: UnixStream) -> Result<()> {
          let mut client = IpcClient::new(stream);
      /// Handle an IPC command
      fn handle_command(&mut self, cmd: Command) -> Response {
          match cmd {
 -            Command::Set { source, mode, monitor: _, interval_secs, shuffle } => {
 +            Command::Set { source, mode, monitor: _, interval_secs, shuffle, animate, max_fps } => {
                  let scale_mode = mode.unwrap_or(self.state.config.general.mode);
 -                // Set up slideshow with the new source
 +                // Stop any existing animation first
 +                self.animation = None;
++
 +                // Check if we should animate (GIF with animate flag)
 +                let is_gif = source.to_lowercase().ends_with(".gif")
 +                    || source.to_lowercase().contains(".gif?")
 +                    || source.to_lowercase().contains("/gif/");
++
 +                if animate && is_gif {
 +                    // Try to start animation
 +                    match self.start_animation(&source, scale_mode, max_fps) {
 +                        Ok(_) => {
 +                            tracing::info!("Animation started: {}", source);
 +                            return Response::ok();
 +                        }
 +                        Err(e) => {
 +                            tracing::warn!("Failed to start animation: {}, falling back to static", e);
 +                            // Fall through to static handling
 +                        }
 +                    }
 +                }
++
 +                // Set up slideshow with the new source (static image)
                  match self.set_wallpaper_with_options(&source, scale_mode, shuffle, interval_secs) {
                      Ok(_) => {
                          // Update slideshow interval
          self.set_wallpaper_from_source(&source, mode, shuffle)
+     }
 +    /// Start an animated GIF playback
 +    fn start_animation(&mut self, source: &str, mode: ScaleMode, max_fps: u32) -> Result<()> {
 +        let is_remote = source.starts_with("http://") || source.starts_with("https://");
++
 +        // Load the GIF
 +        let gif = if is_remote {
 +            tracing::info!("Fetching remote GIF: {}", source);
 +            let bytes = self.fetch_bytes(source)?;
 +            AnimatedGif::load_from_bytes(&bytes)?
 +        } else {
 +            let expanded = shellexpand::tilde(source);
 +            AnimatedGif::load(expanded.as_ref())?
 +        };
++
 +        if !gif.is_animated() {
 +            anyhow::bail!("GIF is not animated (single frame)");
 +        }
++
 +        // Pre-scale all frames
 +        let (width, height) = self.conn.screen_dimensions();
 +        let scaled_frames: Vec<image::RgbaImage> = gif
 +            .frames()
 +            .iter()
 +            .map(|frame| scale_image(&frame.image, width as u32, height as u32, mode))
 +            .collect();
++
 +        // Create animation renderer
 +        let renderer = AnimationRenderer::new(&self.conn)?;
++
 +        tracing::info!(
 +            "Animation loaded: {} frames, {:.1} FPS",
 +            gif.frame_count(),
 +            gif.average_fps()
 +        );
++
 +        self.animation = Some(ActiveAnimation {
 +            gif,
 +            scaled_frames,
 +            renderer,
 +            current_frame: 0,
 +            max_fps,
 +            scale_mode: mode,
 +            source: source.to_string(),
 +        });
++
 +        Ok(())
 +    }
++
 +    /// Fetch raw bytes from a URL
 +    fn fetch_bytes(&self, url: &str) -> Result<Vec<u8>> {
 +        let client = reqwest::blocking::Client::builder()
 +            .user_agent("garbg/0.1")
 +            .build()?;
++
 +        let response = client.get(url).send()?;
 +        let status = response.status();
++
 +        if !status.is_success() {
 +            anyhow::bail!("HTTP error {}: {}", status, url);
 +        }
++
 +        Ok(response.bytes()?.to_vec())
 +    }
++
      /// Set wallpaper with full options (used by IPC Set command)
      fn set_wallpaper_with_options(
          &mut self,

garbg/src/ipc/protocol.rsmodified

  use crate::config::ScaleMode;
 +/// Default max FPS for animations
 +fn default_max_fps() -> u32 {
 +    60
 +}
++
  /// Commands that can be sent to the daemon
  #[derive(Debug, Clone, Serialize, Deserialize)]
  #[serde(tag = "command", rename_all = "snake_case")]
          /// Shuffle the playlist
          #[serde(default)]
          shuffle: bool,
 +        /// Play animated GIFs
 +        #[serde(default)]
 +        animate: bool,
 +        /// Max FPS for animations (default: 60)
 +        #[serde(default = "default_max_fps")]
 +        max_fps: u32,
      },
      /// Set wallpaper for a specific workspace

garbg/src/main.rsmodified

          /// Auto-rotate interval (e.g., "5m", "30s", "1h"). Process stays running.
          #[arg(short, long, value_parser = parse_duration)]
          interval: Option<Duration>,
++
 +        /// Play animated GIFs (auto-detected by default)
 +        #[arg(short, long)]
 +        animate: bool,
++
 +        /// Max FPS for animations (default: 60)
 +        #[arg(long, default_value = "60")]
 +        max_fps: u32,
      },
      /// Advance to the next image in the playlist
          .init();
      match cli.command {
 -        Commands::Set { source, mode, monitor, random, interval } => {
 -            set_wallpaper(&source, &mode, monitor.as_deref(), random, interval)?;
 +        Commands::Set { source, mode, monitor, random, interval, animate, max_fps } => {
 +            set_wallpaper(&source, &mode, monitor.as_deref(), random, interval, animate, max_fps)?;
+         }
          Commands::Next => {
              cmd_next()?;
      _monitor: Option<&str>,
      random: bool,
      interval: Option<Duration>,
 +    animate: bool,
 +    max_fps: u32,
  ) -> Result<()> {
      use garbg::config::ScaleMode;
      use garbg::ipc::{is_daemon_running, send_command_blocking, Command};
      // Normalize GitHub URLs first
      let normalized_source = normalize_github_url(source);
 -    // If daemon is running, delegate to it (especially for interval-based rotation)
 +    // If daemon is running, delegate to it
      if is_daemon_running() {
          let interval_secs = interval.map(|d| d.as_secs());
              monitor: None,
              interval_secs,
              shuffle: random,
 +            animate,
 +            max_fps,
          };
          let response = send_command_blocking(&cmd)?;
          );
+     }
 -    // Set the initial wallpaper
 -    set_single_wallpaper(&resolved_source, scale_mode)?;
 +    // Set the initial wallpaper (handles animated GIFs automatically)
 +    set_single_wallpaper(&resolved_source, scale_mode, animate, max_fps)?;
      // If interval specified and daemon not running, enter foreground rotation loop
 +    // Note: --interval mode doesn't support animations (would require stopping animation to rotate)
      if let Some(interval_duration) = interval {
          if let Some(mut playlist_state) = state {
              tracing::info!(
                  let next_img = playlist_state.next().to_string();
                  playlist_state.save()?;
 -                set_single_wallpaper(&next_img, playlist_state.mode)?;
 +                // Static mode for rotation (animation would conflict)
 +                set_single_wallpaper(&next_img, playlist_state.mode, false, 60)?;
                  tracing::info!(
                      "Rotated to [{}/{}]: {}",
                      playlist_state.current_index + 1,
+ }
  /// Set a single wallpaper (used by set, next, prev)
 -fn set_single_wallpaper(source: &str, mode: garbg::config::ScaleMode) -> Result<()> {
 -    use garbg::media::ImageLoader;
 +///
 +/// If `animate` is true and the source is an animated GIF, this will block
 +/// and play the animation until interrupted (Ctrl+C).
 +fn set_single_wallpaper(
 +    source: &str,
 +    mode: garbg::config::ScaleMode,
 +    animate: bool,
 +    max_fps: u32,
 +) -> Result<()> {
 +    use garbg::daemon::{AnimationConfig, AnimationLoop};
 +    use garbg::media::{AnimatedGif, ImageLoader};
      use garbg::x11::Connection;
      tracing::info!("Setting wallpaper: {}", source);
 +    // Check if source is a GIF file (by extension or URL path)
 +    let is_gif = source.to_lowercase().ends_with(".gif")
 +        || source.to_lowercase().contains(".gif?")  // URL with query params
 +        || source.to_lowercase().contains("/gif/"); // Giphy-style URLs
++
 +    let is_remote = source.starts_with("http://") || source.starts_with("https://");
++
 +    // If it's a GIF and animation is requested, try to load as animated
 +    if is_gif && animate {
 +        // Load GIF data (from file or URL)
 +        let gif_result = if is_remote {
 +            tracing::info!("Fetching remote GIF...");
 +            fetch_gif_from_url(source)
 +        } else {
 +            AnimatedGif::load(source)
 +        };
++
 +        match gif_result {
 +            Ok(gif) if gif.is_animated() => {
 +                // It's an animated GIF - play it
 +                let mut conn = Connection::new()?;
 +                let config = AnimationConfig {
 +                    max_fps,
 +                    adaptive_skip: true,
 +                    scale_mode: mode,
 +                };
++
 +                let mut animation = AnimationLoop::new(gif, &conn, config)?;
++
 +                tracing::info!(
 +                    "Playing animated GIF: {} frames, {:.1} FPS (Ctrl+C to stop)",
 +                    animation.info().frame_count,
 +                    animation.info().average_fps
 +                );
++
 +                // Run animation (blocking until Ctrl+C)
 +                animation.run(&mut conn)?;
++
 +                // Clean up
 +                animation.destroy(&conn);
 +                return Ok(());
 +            }
 +            Ok(_) => {
 +                // Single-frame GIF, fall through to static handling
 +                tracing::debug!("GIF has single frame, treating as static image");
 +            }
 +            Err(e) => {
 +                tracing::debug!("Failed to load as animated GIF: {}, trying as static", e);
 +            }
 +        }
 +    }
++
 +    // Static image handling
      let mut conn = Connection::new()?;
      let image = if source.starts_with("http://") || source.starts_with("https://") {
      let next_image = state.next().to_string();
      state.save()?;
 -    set_single_wallpaper(&next_image, state.mode)?;
 +    // No animation for quick navigation commands
 +    set_single_wallpaper(&next_image, state.mode, false, 60)?;
      tracing::info!(
          "Next [{}/{}]: {}",
      let prev_image = state.prev().to_string();
      state.save()?;
 -    set_single_wallpaper(&prev_image, state.mode)?;
 +    // No animation for quick navigation commands
 +    set_single_wallpaper(&prev_image, state.mode, false, 60)?;
      tracing::info!(
          "Prev [{}/{}]: {}",
      ImageLoader::load_bytes(&bytes, None)
+ }
 +/// Fetch an animated GIF from a URL
 +fn fetch_gif_from_url(url: &str) -> Result<garbg::media::AnimatedGif> {
 +    use garbg::media::AnimatedGif;
++
 +    let client = reqwest::blocking::Client::builder()
 +        .user_agent("garbg/0.1")
 +        .build()?;
++
 +    let response = client.get(url).send()?;
 +    let status = response.status();
++
 +    if !status.is_success() {
 +        anyhow::bail!("HTTP error {}: {}", status, url);
 +    }
++
 +    let bytes = response.bytes()?;
 +    AnimatedGif::load_from_bytes(&bytes)
 +}
++
  /// List images from a source and print them
  fn list_images(source: &str) -> Result<()> {
      let images = list_images_from_source(source)?;

garbg/src/media/gif.rsadded

 +//! Animated GIF decoder with frame-by-frame access
 +//!
 +//! Provides frame extraction and timing information for animated GIFs.
++
 +use anyhow::{Context, Result};
 +use image::codecs::gif::GifDecoder;
 +use image::{AnimationDecoder, Frame, RgbaImage};
 +use std::fs;
 +use std::io::{BufRead, Cursor, Seek};
 +use std::path::Path;
 +use std::time::Duration;
++
 +/// A single animation frame with timing information
 +#[derive(Debug, Clone)]
 +pub struct AnimationFrame {
 +    /// The frame image data
 +    pub image: RgbaImage,
 +    /// Delay before showing the next frame
 +    pub delay: Duration,
 +}
++
 +/// Decoded animated GIF with all frames
 +pub struct AnimatedGif {
 +    /// All frames in order
 +    frames: Vec<AnimationFrame>,
 +    /// Current frame index
 +    current_index: usize,
 +    /// Whether to loop forever
 +    pub loops: bool,
 +    /// Total duration of one loop
 +    pub total_duration: Duration,
 +}
++
 +impl AnimatedGif {
 +    /// Load an animated GIF from a file path
 +    pub fn load<P: AsRef<Path>>(path: P) -> Result<Self> {
 +        let path = path.as_ref();
 +        let data = fs::read(path)
 +            .with_context(|| format!("Failed to read GIF: {}", path.display()))?;
++
 +        Self::load_from_bytes(&data)
 +    }
++
 +    /// Load an animated GIF from bytes
 +    pub fn load_from_bytes(data: &[u8]) -> Result<Self> {
 +        // Use Cursor which implements BufRead + Seek
 +        let cursor = Cursor::new(data.to_vec());
 +        Self::load_from_reader(cursor)
 +    }
++
 +    /// Load from any reader that supports BufRead + Seek
 +    fn load_from_reader<R: BufRead + Seek>(reader: R) -> Result<Self> {
 +        let decoder = GifDecoder::new(reader)
 +            .context("Failed to create GIF decoder")?;
++
 +        let raw_frames = decoder.into_frames();
 +        let mut frames = Vec::new();
 +        let mut total_duration = Duration::ZERO;
++
 +        for frame_result in raw_frames {
 +            let frame: Frame = frame_result.context("Failed to decode GIF frame")?;
 +            let delay = frame_delay_to_duration(&frame);
++
 +            // GIFs with 0 delay often mean "as fast as possible"
 +            // Default to 100ms (10 fps) for reasonable playback
 +            let delay = if delay.is_zero() {
 +                Duration::from_millis(100)
 +            } else {
 +                delay
 +            };
++
 +            total_duration += delay;
++
 +            frames.push(AnimationFrame {
 +                image: frame.into_buffer(),
 +                delay,
 +            });
 +        }
++
 +        if frames.is_empty() {
 +            anyhow::bail!("GIF contains no frames");
 +        }
++
 +        Ok(Self {
 +            frames,
 +            current_index: 0,
 +            loops: true,
 +            total_duration,
 +        })
 +    }
++
 +    /// Get the number of frames
 +    pub fn frame_count(&self) -> usize {
 +        self.frames.len()
 +    }
++
 +    /// Check if this is actually animated (more than one frame)
 +    pub fn is_animated(&self) -> bool {
 +        self.frames.len() > 1
 +    }
++
 +    /// Get the current frame
 +    pub fn current_frame(&self) -> &AnimationFrame {
 +        &self.frames[self.current_index]
 +    }
++
 +    /// Get a specific frame by index
 +    pub fn frame(&self, index: usize) -> Option<&AnimationFrame> {
 +        self.frames.get(index)
 +    }
++
 +    /// Get the current frame index
 +    pub fn current_index(&self) -> usize {
 +        self.current_index
 +    }
++
 +    /// Advance to the next frame, returning true if we looped
 +    pub fn advance(&mut self) -> bool {
 +        self.current_index += 1;
 +        if self.current_index >= self.frames.len() {
 +            self.current_index = 0;
 +            true // Looped
 +        } else {
 +            false
 +        }
 +    }
++
 +    /// Go back to the previous frame
 +    pub fn rewind(&mut self) -> bool {
 +        if self.current_index == 0 {
 +            self.current_index = self.frames.len() - 1;
 +            true // Looped
 +        } else {
 +            self.current_index -= 1;
 +            false
 +        }
 +    }
++
 +    /// Reset to the first frame
 +    pub fn reset(&mut self) {
 +        self.current_index = 0;
 +    }
++
 +    /// Get all frames as a slice
 +    pub fn frames(&self) -> &[AnimationFrame] {
 +        &self.frames
 +    }
++
 +    /// Get average FPS
 +    pub fn average_fps(&self) -> f64 {
 +        if self.total_duration.is_zero() {
 +            return 0.0;
 +        }
 +        self.frames.len() as f64 / self.total_duration.as_secs_f64()
 +    }
++
 +    /// Get dimensions (width, height) from first frame
 +    pub fn dimensions(&self) -> (u32, u32) {
 +        let first = &self.frames[0].image;
 +        (first.width(), first.height())
 +    }
 +}
++
 +/// Convert frame delay ratio to Duration
 +fn frame_delay_to_duration(frame: &Frame) -> Duration {
 +    let (numerator, denominator) = frame.delay().numer_denom_ms();
 +    if denominator == 0 {
 +        Duration::ZERO
 +    } else {
 +        Duration::from_millis((numerator as u64 * 1000) / denominator as u64)
 +    }
 +}
++
 +/// Check if a file is likely an animated GIF (has multiple frames)
 +pub fn is_animated_gif<P: AsRef<Path>>(path: P) -> bool {
 +    // Quick check: try to load and see if it has multiple frames
 +    match AnimatedGif::load(path) {
 +        Ok(gif) => gif.is_animated(),
 +        Err(_) => false,
 +    }
 +}
++
 +#[cfg(test)]
 +mod tests {
 +    use super::*;
++
 +    #[test]
 +    fn test_frame_delay_conversion() {
 +        // A frame with 100ms delay (10 centiseconds)
 +        // GIF delays are typically in centiseconds
 +    }
 +}

garbg/src/media/mod.rsmodified

  mod loader;
  mod scaler;
 +mod gif;
  pub use loader::ImageLoader;
  pub use scaler::scale_image;
 +pub use gif::{AnimatedGif, AnimationFrame, is_animated_gif};
  // Re-export ScaleMode from config for convenience
  pub use crate::config::ScaleMode;

garbg/src/x11/animation.rsadded

 +//! Animation support with double buffering
 +//!
 +//! Provides smooth animation playback using double-buffered pixmaps.
++
 +use anyhow::Result;
 +use x11rb::protocol::xproto::*;
 +use x11rb::connection::Connection as X11Connection;
 +use x11rb::wrapper::ConnectionExt as _;
++
 +use super::Connection;
++
 +/// Double buffer for smooth animation rendering
 +pub struct DoubleBuffer {
 +    /// Front buffer (currently displayed)
 +    front: Pixmap,
 +    /// Back buffer (being rendered to)
 +    back: Pixmap,
 +    /// Screen dimensions
 +    width: u16,
 +    height: u16,
 +}
++
 +impl DoubleBuffer {
 +    /// Create a new double buffer with the given dimensions
 +    pub fn new(conn: &Connection) -> Result<Self> {
 +        let (width, height) = conn.screen_dimensions();
 +        let depth = conn.depth();
 +        let root = conn.root();
 +        let x11_conn = conn.conn();
++
 +        // Create front buffer
 +        let front = x11_conn.generate_id()?;
 +        x11_conn.create_pixmap(depth, front, root, width, height)?;
++
 +        // Create back buffer
 +        let back = x11_conn.generate_id()?;
 +        x11_conn.create_pixmap(depth, back, root, width, height)?;
++
 +        Ok(Self {
 +            front,
 +            back,
 +            width,
 +            height,
 +        })
 +    }
++
 +    /// Get the back buffer to render to
 +    pub fn back_buffer(&self) -> Pixmap {
 +        self.back
 +    }
++
 +    /// Get the front buffer (currently displayed)
 +    pub fn front_buffer(&self) -> Pixmap {
 +        self.front
 +    }
++
 +    /// Swap front and back buffers
 +    pub fn swap(&mut self) {
 +        std::mem::swap(&mut self.front, &mut self.back);
 +    }
++
 +    /// Get dimensions
 +    pub fn dimensions(&self) -> (u16, u16) {
 +        (self.width, self.height)
 +    }
++
 +    /// Free the pixmaps
 +    pub fn destroy(&self, conn: &Connection) {
 +        let x11_conn = conn.conn();
 +        let _ = x11_conn.free_pixmap(self.front);
 +        let _ = x11_conn.free_pixmap(self.back);
 +    }
 +}
++
 +/// Animation renderer using double buffering
 +pub struct AnimationRenderer {
 +    /// Double buffer for smooth rendering
 +    buffer: DoubleBuffer,
 +}
++
 +impl AnimationRenderer {
 +    /// Create a new animation renderer
 +    pub fn new(conn: &Connection) -> Result<Self> {
 +        let buffer = DoubleBuffer::new(conn)?;
 +        Ok(Self { buffer })
 +    }
++
 +    /// Render a frame to the back buffer
 +    pub fn render_frame(&mut self, conn: &mut Connection, frame: &image::RgbaImage) -> Result<()> {
 +        let (width, height) = self.buffer.dimensions();
++
 +        // Convert RGBA to BGRA (X11 native format)
 +        let bgra_data = rgba_to_bgra(frame);
++
 +        let gc = conn.gc();
 +        let x11_conn = conn.conn();
 +        let depth = conn.depth();
 +        let back = self.buffer.back_buffer();
++
 +        // Calculate chunking for large images
 +        let max_request_bytes = x11_conn.setup().maximum_request_length as usize * 4;
 +        let bytes_per_row = width as usize * 4;
 +        let request_overhead = 28;
 +        let max_rows_per_request = ((max_request_bytes - request_overhead) / bytes_per_row).max(1) as u16;
++
 +        // Send image in chunks
 +        let mut y_offset: u16 = 0;
 +        while y_offset < height {
 +            let rows_to_send = (height - y_offset).min(max_rows_per_request);
 +            let start_byte = y_offset as usize * bytes_per_row;
 +            let end_byte = (y_offset as usize + rows_to_send as usize) * bytes_per_row;
 +            let chunk = &bgra_data[start_byte..end_byte];
++
 +            x11_conn.put_image(
 +                ImageFormat::Z_PIXMAP,
 +                back,
 +                gc,
 +                width,
 +                rows_to_send,
 +                0,
 +                y_offset as i16,
 +                0,
 +                depth,
 +                chunk,
 +            )?;
++
 +            y_offset += rows_to_send;
 +        }
++
 +        Ok(())
 +    }
++
 +    /// Present the back buffer (swap and display)
 +    pub fn present(&mut self, conn: &mut Connection) -> Result<()> {
 +        // Swap buffers
 +        self.buffer.swap();
++
 +        // Set the new front buffer as root background
 +        let front = self.buffer.front_buffer();
 +        let root = conn.root();
 +        let x11_conn = conn.conn();
 +        let atoms = conn.atoms();
++
 +        // Set the standard atoms for compatibility
 +        x11_conn.change_property32(
 +            PropMode::REPLACE,
 +            root,
 +            atoms.xrootpmap_id,
 +            AtomEnum::PIXMAP,
 +            &[front],
 +        )?;
++
 +        x11_conn.change_property32(
 +            PropMode::REPLACE,
 +            root,
 +            atoms.esetroot_pmap_id,
 +            AtomEnum::PIXMAP,
 +            &[front],
 +        )?;
++
 +        // Set as background and clear
 +        x11_conn.change_window_attributes(
 +            root,
 +            &ChangeWindowAttributesAux::new().background_pixmap(front),
 +        )?;
++
 +        let (width, height) = self.buffer.dimensions();
 +        x11_conn.clear_area(false, root, 0, 0, width, height)?;
 +        x11_conn.flush()?;
++
 +        Ok(())
 +    }
++
 +    /// Render and present in one call
 +    pub fn render_and_present(&mut self, conn: &mut Connection, frame: &image::RgbaImage) -> Result<()> {
 +        self.render_frame(conn, frame)?;
 +        self.present(conn)
 +    }
++
 +    /// Get dimensions
 +    pub fn dimensions(&self) -> (u16, u16) {
 +        self.buffer.dimensions()
 +    }
++
 +    /// Clean up resources
 +    pub fn destroy(self, conn: &Connection) {
 +        self.buffer.destroy(conn);
 +    }
 +}
++
 +/// Convert RGBA to BGRA (X11 native format for 32-bit visuals)
 +fn rgba_to_bgra(image: &image::RgbaImage) -> Vec<u8> {
 +    let mut bgra = Vec::with_capacity(image.len());
 +    for pixel in image.pixels() {
 +        bgra.push(pixel[2]); // B
 +        bgra.push(pixel[1]); // G
 +        bgra.push(pixel[0]); // R
 +        bgra.push(pixel[3]); // A
 +    }
 +    bgra
 +}

garbg/src/x11/connection.rsmodified

  use x11rb::rust_connection::RustConnection;
  use x11rb::wrapper::ConnectionExt as _;
 +/// X11 connection errors with helpful messages
 +#[derive(Debug, thiserror::Error)]
 +pub enum X11Error {
 +    #[error("DISPLAY environment variable not set. Is an X11 server running?")]
 +    NoDisplay,
++
 +    #[error("Failed to connect to X server at '{display}': {source}. Is the X server running?")]
 +    ConnectionFailed {
 +        display: String,
 +        #[source]
 +        source: x11rb::errors::ConnectError,
 +    },
++
 +    #[error("X11 operation failed: {0}")]
 +    Protocol(#[from] x11rb::errors::ConnectionError),
++
 +    #[error("X11 reply error: {0}")]
 +    Reply(#[from] x11rb::errors::ReplyError),
 +}
++
  /// Interned X11 atoms for wallpaper operations
  pub struct Atoms {
      /// Standard atom for root pixmap (used by many apps)
  impl Connection {
      /// Create a new X11 connection
 +    ///
 +    /// Returns helpful error messages if X11 is not available:
 +    /// - Checks for DISPLAY environment variable
 +    /// - Provides actionable error messages for common failures
      pub fn new() -> Result<Self> {
 -        let (conn, screen_num) = RustConnection::connect(None)
 -            .context("Failed to connect to X server")?;
 +        // Check DISPLAY environment variable first for a better error message
 +        let display = std::env::var("DISPLAY").ok();
 +        if display.is_none() {
 +            return Err(X11Error::NoDisplay.into());
 +        }
++
 +        let (conn, screen_num) = match RustConnection::connect(None) {
 +            Ok(result) => result,
 +            Err(e) => {
 +                return Err(X11Error::ConnectionFailed {
 +                    display: display.unwrap_or_else(|| "unknown".to_string()),
 +                    source: e,
 +                }.into());
 +            }
 +        };
          let screen = &conn.setup().roots[screen_num];
          let root = screen.root;
          &self.atoms
+     }
 +    /// Check if the X11 connection is still alive
 +    ///
 +    /// Performs a round-trip to the X server to verify connectivity.
 +    /// Returns false if the connection is broken.
 +    pub fn is_alive(&self) -> bool {
 +        // GetInputFocus is a cheap round-trip to verify connection health
 +        self.conn.get_input_focus().is_ok()
 +            && self.conn.sync().is_ok()
 +    }
++
      /// Set a wallpaper from BGRA image data
      pub fn set_wallpaper(&mut self, image: &image::RgbaImage) -> Result<()> {
          let (width, height) = self.screen_dimensions();

garbg/src/x11/mod.rsmodified

  mod connection;
  mod renderer;
  mod monitors;
 +mod animation;
 -pub use connection::Connection;
 +pub use connection::{Connection, X11Error};
  pub use renderer::Renderer;
  pub use monitors::Monitor;
 +pub use animation::{AnimationRenderer, DoubleBuffer};