refactor + minor fixes

Author: minhcrafters

.gitignore

@@ -1,6 +1,7 @@
 *.mp4
 *.wav
 *.exe
+
 data/
 videos/
 
@@ -11,6 +12,8 @@ Cargo.lock
 debug/
 target/
 
+.idea/
+
 # These are backup files generated by rustfmt
 **/*.rs.bk
 

Cargo.toml

@@ -4,33 +4,22 @@ version = "0.1.0"
 edition = "2024"
 
 [dependencies]
-clap = { version = "4.5", features = ["derive"] } # Argument parsing
-crossterm = "0.29"          # Terminal manipulation (size, cursor, raw mode, colors, events)
-image = "0.25"              # Image loading, processing, resizing
-rodio = { version = "0.20", features = ["wav"] } # Audio playback (using wav format from ffmpeg)
-zstd = "0.13"               # Zstandard compression/decompression
-sha2 = "0.10"               # SHA-256 hashing
-rayon = "1.10"              # Data parallelism (for frame processing)
-indicatif = "0.17"          # Progress bars
-sysinfo = "0.34"           # System information (CPU/Memory)
-chrono = "0.4"             # Time/Duration formatting
-thiserror = "2.0"          # Error handling helper
-log = "0.4"                # Logging facade
+clap = { version = "4.5", features = ["derive"] }
+crossterm = "0.29"
+image = "0.25"
+rodio = { version = "0.20", features = ["wav"] }
+zstd = "0.13"
+sha2 = "0.10"
+rayon = "1.10"
+indicatif = "0.17"
+sysinfo = "0.35"
+thiserror = "2.0"
+log = "0.4"
 ctrlc = "3.4"
-env_logger = "0.11"         # Logging implementation
-lazy_static = "1.5"         # For static initialization (like ASCII_CHARS)
-tempfile = "3.19"           # For temporary directories/files if needed during frame extraction
-cpal = "0.15"   # Audio output and device handling
-hound = "3.5"   # Wav file reading
-ringbuf = "0.4"
-crossbeam-channel = "0.5"
-ftail = "0.2"
-log4rs = "1.3"
+lazy_static = "1.5"
+tempfile = "3.20"
+hound = "3.5"
 serde = { version = "1.0", features = ["derive"] }
 serde_cbor = "0.11.2"
+log4rs = "1.3.0"
 
-# [profile.release]
-# lto = true           # Link-Time Optimization
-# codegen-units = 1    # Optimize for speed over compile time
-# panic = 'abort'      # Abort on panic for smaller binary size (optional)
-# strip = true         # Strip symbols

README.md

@@ -0,0 +1,25 @@
+# ascii-rs
+
+A small Rust command line tool that plays videos as _coloured_ ASCII art directly in your terminal with minimal performance overhead.
+
+## Steps to run
+
+-   If not already, install Rust [via rustup](https://rustup.rs) and FFmpeg (ffmpeg must be on your system PATH).
+-   Put a video file somewhere on your machine (e.g., videos/sample.mp4).
+-   From the project root, run in your terminal:
+    -   Debug: `cargo run -- <path-to-video>`
+    -   Release: `cargo run --release -- <path-to-video>`
+-   Use Ctrl+C to stop playback at any time.
+
+## Screenshots
+
+![sync_test.png](img/sync_test.png)
+
+![steve.png](img/steve.png)
+
+## Notes
+
+-   Tested on Windows Terminal (Powershell), not sure about other terminals.
+-   Larger terminals look better; a minimum of ~100x80 is recommended.
+-   A cache file is created to speed up subsequent runs of the same video.
+-   Add --regenerate to force rebuilding the ASCII cache for that video.

build.bat

@@ -0,0 +1,5 @@
+@echo off
+
+cargo build --release
+
+copy /v /y .\target\release\*.exe .

img/steve.png

@@ -1,12 +1,16 @@
-use crate::config::{ASCII_CHARS, CHAR_ASPECT_RATIO};
-use crate::error::AppError;
-use image::imageops::FilterType;
-use image::{DynamicImage, GenericImageView, ImageBuffer, Rgb};
+use crate::{
+    config::{ASCII_CHARS, CHAR_ASPECT_RATIO},
+    error::AppError,
+};
+use image::{DynamicImage, GenericImageView, ImageBuffer, Rgb, RgbImage, imageops::FilterType};
 use indicatif::{ProgressBar, ProgressStyle};
+use log::{debug, error, info};
 use rayon::prelude::*;
 use serde::{Deserialize, Serialize};
-use std::path::{Path, PathBuf};
-use std::sync::Mutex;
+use std::{
+    path::{Path, PathBuf},
+    sync::Mutex,
+};
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct RleRun {
@@ -21,7 +25,9 @@ pub struct RleFrame {
     pub runs: Vec<RleRun>,
 }
 
-fn resize_and_center(img: &DynamicImage, cols: u16, lines: u16) -> ImageBuffer<Rgb<u8>, Vec<u8>> {
+pub fn resize_and_center(img: &DynamicImage, cols: u16, lines: u16) -> RgbImage {
+    debug!("Resizing image to fit terminal: {}x{}", cols, lines);
+
     let term_w = cols as u32;
     let term_h = lines.saturating_sub(1) as u32;
     if term_w == 0 || term_h == 0 {
@@ -53,7 +59,7 @@ fn resize_and_center(img: &DynamicImage, cols: u16, lines: u16) -> ImageBuffer<R
     canvas
 }
 
-fn convert_image_to_ascii(img: &ImageBuffer<Rgb<u8>, Vec<u8>>) -> RleFrame {
+pub fn convert_image_to_ascii(img: &RgbImage) -> RleFrame {
     let (w, h) = img.dimensions();
     if w == 0 || h == 0 {
         return RleFrame {
@@ -105,43 +111,52 @@ fn convert_image_to_ascii(img: &ImageBuffer<Rgb<u8>, Vec<u8>>) -> RleFrame {
     }
 }
 
-fn process_single_frame(path: &Path, size: (u16, u16)) -> Result<RleFrame, AppError> {
-    let img = image::open(path)?;
-    let buf = resize_and_center(&img, size.0, size.1);
-    Ok(convert_image_to_ascii(&buf))
+pub fn process_single_frame(path: &Path, size: (u16, u16)) -> Result<RleFrame, AppError> {
+    debug!("Processing frame: {}", path.display());
+
+    let img = image::open(path).map_err(|e| {
+        error!("Failed to open image at {}: {}", path.display(), e);
+        AppError::Image {
+            source: e,
+            context: Some(path.display().to_string()),
+        }
+    })?;
+
+    let img = resize_and_center(&img, size.0, size.1);
+    Ok(convert_image_to_ascii(&img))
 }
 
 pub fn process_frames_parallel(
     paths: &[PathBuf],
     size: (u16, u16),
 ) -> Result<Vec<RleFrame>, AppError> {
-    if paths.is_empty() {
-        return Ok(Vec::new());
-    }
-    let pb = ProgressBar::new(paths.len() as u64);
-    pb.set_style(
-        ProgressStyle::default_bar()
-            .template("Generating ASCII frames:  [{elapsed_precise}] [{bar:40.cyan/blue}] {pos}/{len} ({eta})")
-            .unwrap()
-            .progress_chars("=> "),
+    info!("Processing {} frames", paths.len());
+
+    let pb = Mutex::new(
+        ProgressBar::new(paths.len() as u64)
+            .with_style(
+                ProgressStyle::default_bar()
+                    .template("{spinner:.green} [{elapsed_precise}] [{bar:40.cyan/blue}] {pos}/{len} ({eta})")
+                    .unwrap()
+                    .progress_chars("##-")
+            )
+            .with_message("Processing frames"),
     );
-    let m = Mutex::new(pb);
-    let mut frames = Vec::with_capacity(paths.len());
-    let results: Vec<_> = paths
+
+    let results: Result<Vec<_>, _> = paths
         .par_iter()
-        .map(|p| {
-            let f = process_single_frame(p, size);
-            if let Ok(ref pb) = m.lock() {
-                pb.inc(1);
+        .map(|path| {
+            let result = process_single_frame(path, size);
+            if let Ok(pb_lock) = pb.lock() {
+                pb_lock.inc(1);
             }
-            f
+            result
         })
         .collect();
-    for res in results {
-        frames.push(res?);
-    }
-    if let Ok(pb) = m.lock() {
-        pb.finish_and_clear();
+
+    if let Ok(pb_lock) = pb.lock() {
+        pb_lock.finish_with_message("Frame processing complete");
     }
-    Ok(frames)
+
+    results
 }

img/sync_test.png

@@ -4,10 +4,10 @@ use std::path::PathBuf;
 #[derive(Parser, Debug)]
 #[command(author, version, about = "Plays videos in the terminal using ASCII characters", long_about = None)]
 pub struct CliArgs {
-    #[arg(short, long)]
-    pub video: Option<PathBuf>,
+    #[arg(required = true)]
+    pub video: PathBuf,
 
-    #[arg(short, long, action = clap::ArgAction::SetTrue)]
+    #[arg(action = clap::ArgAction::SetTrue)]
     pub regenerate: bool,
 }
 

src/ascii.rs

@@ -7,20 +7,35 @@ use thiserror::Error;
 
 #[derive(Error, Debug)]
 pub enum AppError {
-    #[error("I/O error: {0}")]
-    Io(#[from] std::io::Error),
-
-    #[error("Image processing error: {0}")]
-    Image(#[from] ImageError),
-
-    #[error("Audio playback error: {0}")]
-    AudioPlayback(#[from] PlayError),
-
-    #[error("Audio decoding error: {0}")]
-    AudioDecode(#[from] DecoderError),
-
-    #[error("Terminal error: {0}")]
-    Terminal(std::io::Error),
+    #[error("I/O error: {source}")]
+    Io {
+        source: std::io::Error,
+        context: Option<String>,
+    },
+
+    #[error("Image processing error: {source}")]
+    Image {
+        source: ImageError,
+        context: Option<String>,
+    },
+
+    #[error("Audio playback error: {source}")]
+    AudioPlayback {
+        source: PlayError,
+        context: Option<String>,
+    },
+
+    #[error("Audio decoding error: {source}")]
+    AudioDecode {
+        source: DecoderError,
+        context: Option<String>,
+    },
+
+    #[error("Terminal error: {source}")]
+    Terminal {
+        source: std::io::Error,
+        context: Option<String>,
+    },
 
     #[error("FFmpeg command failed: {0}")]
     FFmpeg(String),
@@ -49,20 +64,36 @@ pub enum AppError {
     #[error("Unsupported ACSV version: {0}")]
     UnsupportedAcsvVersion(u8),
 
-    #[error("Failed to parse integer: {0}")]
-    ParseInt(#[from] ParseIntError),
-
-    #[error("Failed to parse float: {0}")]
-    ParseFloat(#[from] ParseFloatError),
-
-    #[error("Failed to decode UTF-8: {0}")]
-    Utf8(#[from] FromUtf8Error),
-
-    #[error("Compression error: {0}")]
-    Compression(std::io::Error),
-
-    #[error("Decompression error: {0}")]
-    Decompression(std::io::Error),
+    #[error("Failed to parse integer: {source}")]
+    ParseInt {
+        source: ParseIntError,
+        context: Option<String>,
+    },
+
+    #[error("Failed to parse float: {source}")]
+    #[allow(dead_code)]
+    ParseFloat {
+        source: ParseFloatError,
+        context: Option<String>,
+    },
+
+    #[error("Failed to decode UTF-8: {source}")]
+    Utf8 {
+        source: FromUtf8Error,
+        context: Option<String>,
+    },
+
+    #[error("Compression error: {source}")]
+    Compression {
+        source: std::io::Error,
+        context: Option<String>,
+    },
+
+    #[error("Decompression error: {source}")]
+    Decompression {
+        source: std::io::Error,
+        context: Option<String>,
+    },
 
     #[error("Frame processing failed")]
     FrameProcessing,
@@ -82,7 +113,3 @@ pub enum AppError {
     #[error("Could not get system information: {0}")]
     SystemInfo(String),
 }
-
-pub fn map_terminal_error(e: std::io::Error) -> AppError {
-    AppError::Terminal(e)
-}