feat: configurable framerate for smoother animations (#296)

## Summary

Adds a new `--fps` option to make typing animations smoother. Perfect
for demos and presentations where you want fluid, professional-looking
recordings.

### The Problem

The default 4 fps capture rate can make fast typing appear choppy.
Multiple keystrokes within a 250ms window get compressed into a single
frame, making the animation feel "jumpy".

### The Solution

You can now increase the capture framerate up to 15 fps for smoother
animations:

```sh
# Smooth typing (10 fps, 100ms intervals)
t-rec --fps 10

# Very smooth (15 fps, 66ms intervals)
t-rec --fps 15

# Or use the new preset profile
t-rec --profile smooth
```

### Usage Examples

| FPS | Interval | Best For |
|-----|----------|----------|
| 4 (default) | 250ms | Regular recordings, smaller files |
| 10 | 100ms | Demos, presentations |
| 15 | 66ms | Fast typing, smooth cursor movement |

### Config File Support

You can save your preferred framerate in the config file:

```toml
[default]
fps = 10

[profiles.smooth]
fps = 10
idle-pause = "2s"
```

### Trade-offs

Higher framerates produce larger files (roughly proportional to fps
increase). The idle frame detection still works, so file sizes are
optimized during pauses.

## Test plan

- [x] `cargo build` succeeds
- [x] `cargo test` passes
- [x] `cargo clippy` passes
- [x] Manual test: `t-rec --fps 4` (default behavior)
- [x] Manual test: `t-rec --fps 10` (visibly smoother)
- [x] Manual test: `t-rec --fps 15` (very smooth)
- [x] Manual test: `t-rec --fps 3` errors (below minimum)
- [x] Manual test: `t-rec --fps 16` errors (above maximum)
- [x] Manual test: Config file with `fps = 10` works

Completes #28

---------

Signed-off-by: Sven Kanoldt <sven@d34dl0ck.me>

Author: sassman

README.md

@@ -18,7 +18,7 @@ Blazingly fast terminal recorder that generates animated gif images for the web
 ![demo](./docs/demo.gif)
 
 ## Features
-- Screenshotting your terminal with 4 frames per second (every 250ms)
+- Screenshotting your terminal with configurable framerate (4-15 fps)
 - Generates high quality small sized animated gif images or mp4 videos
 - **built-in idle frames detection and optimization** (for super fluid presentations)
 - Applies (can be disabled) border decor effects like drop shadow
@@ -168,6 +168,8 @@ Options:
   -i, --idle-pause <s | ms | m>   to preserve natural pauses up to a maximum duration by overriding
                                   idle detection. Can enhance readability. [default: 3s]
   -o, --output <file>             to specify the output file (without extension) [default: t-rec]
+  -f, --fps <4-15>                Capture framerate. Higher = smoother animations but larger
+                                  files [default: 4]
   -p, --wallpaper <wallpaper>     Wallpaper background. Use 'ventura' for built-in, or provide
                                   a path to a custom image (PNG, JPEG, TGA)
       --wallpaper-padding <1-500> Padding in pixels around the recording when using --wallpaper
@@ -259,9 +261,24 @@ t-rec --list-profiles
 | `end-pause` | string | Pause at end |
 | `idle-pause` | string | Max idle time before optimization |
 | `output` | string | Output filename (without extension) |
+| `fps` | number | Capture framerate, 4-15 (default: 4) |
 
 **Note:** CLI arguments always override config file settings.
 
+### Smoother Animations
+
+For smoother typing animations in demos, increase the capture framerate:
+
+```sh
+# Smooth typing (10 fps)
+t-rec --fps 10
+
+# Very smooth (15 fps)
+t-rec --fps 15
+```
+
+**Note:** Higher framerates produce larger files. The default 4 fps is recommended for most use cases.
+
 ### Disable idle detection & optimization
 
 If you are not happy with the idle detection and optimization, you can disable it with the `-n` or `--natural` parameter.

src/capture.rs

@@ -11,6 +11,36 @@ use tempfile::TempDir;
 use crate::utils::{file_name_for, IMG_EXT};
 use crate::{ImageOnHeap, PlatformApi, WindowId};
 
+/// Configuration and shared state for the capture thread.
+///
+/// Groups all parameters needed for frame capture, making the API cleaner
+/// and easier to extend with new options.
+pub struct CaptureContext {
+    /// Window ID to capture
+    pub win_id: WindowId,
+    /// Shared list to store frame timestamps
+    pub time_codes: Arc<Mutex<Vec<u128>>>,
+    /// Directory for saving frames
+    pub tempdir: Arc<Mutex<TempDir>>,
+    /// If true, save all frames without idle detection
+    pub natural: bool,
+    /// Maximum pause duration to preserve (None = skip all identical frames)
+    pub idle_pause: Option<Duration>,
+    /// Capture framerate (4-15 fps)
+    pub fps: u8,
+}
+
+impl CaptureContext {
+    /// Calculate frame interval from fps, this is not used in tests
+    pub fn frame_interval(&self) -> Duration {
+        if cfg!(test) {
+            Duration::from_millis(10) // Fast for testing
+        } else {
+            Duration::from_millis(1000 / self.fps as u64)
+        }
+    }
+}
+
 /// Captures screenshots periodically and decides which frames to keep.
 ///
 /// Eliminates long idle periods while preserving brief pauses that aid
@@ -19,13 +49,7 @@ use crate::{ImageOnHeap, PlatformApi, WindowId};
 /// # Parameters
 /// * `rx` - Channel to receive stop signal
 /// * `api` - Platform API for taking screenshots
-/// * `win_id` - Window ID to capture
-/// * `time_codes` - Shared list to store frame timestamps
-/// * `tempdir` - Directory for saving frames
-/// * `force_natural` - If true, save all frames (no skipping)
-/// * `idle_pause` - Maximum pause duration to preserve for viewer comprehension:
-///   - `None`: Skip all identical frames (maximum compression)
-///   - `Some(duration)`: Preserve pauses up to this duration, skip beyond
+/// * `ctx` - Capture configuration and shared state
 ///
 /// # Behavior
 /// When identical frames are detected:
@@ -34,19 +58,8 @@ use crate::{ImageOnHeap, PlatformApi, WindowId};
 ///
 /// Example: 10-second idle with 3-second threshold → saves 3 seconds of pause,
 ///          skips 7 seconds, playback shows exactly 3 seconds.
-pub fn capture_thread(
-    rx: &Receiver<()>,
-    api: impl PlatformApi,
-    win_id: WindowId,
-    time_codes: Arc<Mutex<Vec<u128>>>,
-    tempdir: Arc<Mutex<TempDir>>,
-    force_natural: bool,
-    idle_pause: Option<Duration>,
-) -> Result<()> {
-    #[cfg(test)]
-    let duration = Duration::from_millis(10); // Fast for testing
-    #[cfg(not(test))]
-    let duration = Duration::from_millis(250); // Production speed
+pub fn capture_thread(rx: &Receiver<()>, api: impl PlatformApi, ctx: CaptureContext) -> Result<()> {
+    let duration = ctx.frame_interval();
     let start = Instant::now();
 
     // Total idle time skipped (subtracted from timestamps to prevent gaps)
@@ -68,11 +81,11 @@ pub fn capture_thread(
         let effective_now = now.sub(idle_duration);
         let tc = effective_now.saturating_duration_since(start).as_millis();
 
-        let image = api.capture_window_screenshot(win_id)?;
+        let image = api.capture_window_screenshot(ctx.win_id)?;
         let frame_duration = now.duration_since(last_now);
 
         // Check if frame is identical to previous (skip check in natural mode)
-        let frame_unchanged = !force_natural
+        let frame_unchanged = !ctx.natural
             && last_frame
                 .as_ref()
                 .map(|last| image.samples.as_slice() == last.samples.as_slice())
@@ -87,7 +100,7 @@ pub fn capture_thread(
 
         // Decide whether to save this frame
         let should_save_frame = if frame_unchanged {
-            let should_skip_for_compression = if let Some(threshold) = idle_pause {
+            let should_skip_for_compression = if let Some(threshold) = ctx.idle_pause {
                 // Skip if idle exceeds threshold
                 current_idle_period >= threshold
             } else {
@@ -111,12 +124,16 @@ pub fn capture_thread(
 
         if should_save_frame {
             // Save frame and update state
-            if let Err(e) = save_frame(&image, tc, tempdir.lock().unwrap().borrow(), file_name_for)
-            {
+            if let Err(e) = save_frame(
+                &image,
+                tc,
+                ctx.tempdir.lock().unwrap().borrow(),
+                file_name_for,
+            ) {
                 eprintln!("{}", &e);
                 return Err(e);
             }
-            time_codes.lock().unwrap().push(tc);
+            ctx.time_codes.lock().unwrap().push(tc);
 
             // Store frame for next comparison
             last_frame = Some(image);
@@ -230,16 +247,15 @@ mod tests {
             let _ = stop_signal_tx.send(());
         });
 
-        let timestamps_clone = captured_timestamps.clone();
-        capture_thread(
-            &stop_signal_rx,
-            test_api,
-            0,
-            timestamps_clone,
-            temp_directory,
-            natural_mode,
-            idle_threshold,
-        )?;
+        let ctx = CaptureContext {
+            win_id: 0,
+            time_codes: captured_timestamps.clone(),
+            tempdir: temp_directory,
+            natural: natural_mode,
+            idle_pause: idle_threshold,
+            fps: 4, // Default fps for tests
+        };
+        capture_thread(&stop_signal_rx, test_api, ctx)?;
         let result = captured_timestamps.lock().unwrap().clone();
         Ok(result)
     }

src/cli.rs

@@ -138,6 +138,15 @@ pub fn launch() -> ArgMatches {
                 .default_value("t-rec")
                 .help("to specify the output file (without extension)"),
         )
+        .arg(
+            Arg::new("fps")
+                .value_parser(clap::value_parser!(u8).range(4..=15))
+                .default_value("4")
+                .required(false)
+                .short('f')
+                .long("fps")
+                .help("Capture framerate, 4-15 fps. Higher = smoother animations but larger files"),
+        )
         .arg(
             Arg::new("program")
                 .value_name("shell or program to launch")

src/config/init.rs

@@ -3,6 +3,7 @@ pub const STARTER_CONFIG: &str = r#"# t-rec configuration file
 
 # Default settings applied to all recordings
 [default]
+# fps = 4
 # wallpaper = "ventura"
 # wallpaper-padding = 60
 # start-pause = "2s"
@@ -16,6 +17,10 @@ wallpaper-padding = 100
 start-pause = "5s"
 idle-pause = "5s"
 
+[profiles.smooth]
+fps = 10
+idle-pause = "2s"
+
 [profiles.quick]
 quiet = true
 idle-pause = "1s"

src/config/profile.rs

@@ -21,6 +21,7 @@ pub struct ProfileSettings {
     pub start_pause: Option<String>,
     pub idle_pause: Option<String>,
     pub output: Option<String>,
+    pub fps: Option<u8>,
 }
 
 impl ProfileSettings {
@@ -65,6 +66,9 @@ impl ProfileSettings {
         if other.output.is_some() {
             self.output = other.output.clone();
         }
+        if other.fps.is_some() {
+            self.fps = other.fps;
+        }
     }
 
     /// Apply CLI arguments on top of config settings
@@ -122,6 +126,11 @@ impl ProfileSettings {
                 self.output = Some(v.clone());
             }
         }
+        if args.value_source("fps") == Some(clap::parser::ValueSource::CommandLine) {
+            if let Some(v) = args.get_one::<u8>("fps") {
+                self.fps = Some(*v);
+            }
+        }
     }
 
     /// Get final values with defaults applied
@@ -155,6 +164,10 @@ impl ProfileSettings {
     pub fn output(&self) -> &str {
         self.output.as_deref().unwrap_or("t-rec")
     }
+    /// Get fps value (default: 4, must be kept in sync with CLI default)
+    pub fn fps(&self) -> u8 {
+        self.fps.unwrap_or(4)
+    }
 }
 
 /// Expand $HOME in a string value (only $HOME is supported)
@@ -252,5 +265,6 @@ mod tests {
         assert_eq!(settings.wallpaper_padding(), 60);
         assert_eq!(settings.idle_pause(), "3s");
         assert_eq!(settings.output(), "t-rec");
+        assert_eq!(settings.fps(), 4);
     }
 }

src/generators/gif.rs

@@ -45,7 +45,7 @@ pub fn generate_gif_with_convert(
         if !frame.exists() {
             continue;
         }
-        let mut frame_delay = (delay as f64 * 0.1) as u64;
+        let mut frame_delay = ((delay as f64 * 0.1).round() as u64).max(1);
         match (i, start_pause, end_pause) {
             (0, Some(delay), _) => {
                 frame_delay += delay.as_millis().div(10) as u64;

src/main.rs

@@ -4,6 +4,7 @@ mod common;
 mod config;
 mod decors;
 mod generators;
+mod summary;
 mod tips;
 mod wallpapers;
 
@@ -31,13 +32,14 @@ use crate::config::{
 };
 use crate::decors::{apply_big_sur_corner_effect, apply_shadow_effect};
 use crate::generators::{check_for_gif, check_for_mp4, generate_gif, generate_mp4};
+use crate::summary::print_recording_summary;
 use crate::tips::show_tip;
 use crate::wallpapers::{
     apply_wallpaper_effect, get_ventura_wallpaper, is_builtin_wallpaper,
     load_and_validate_wallpaper,
 };
 
-use crate::capture::capture_thread;
+use crate::capture::{capture_thread, CaptureContext};
 use crate::utils::{sub_shell_thread, target_file, DEFAULT_EXT, MOVIE_EXT};
 use anyhow::{bail, Context};
 use clap::ArgMatches;
@@ -107,14 +109,14 @@ fn main() -> Result<()> {
     // Validate wallpaper BEFORE recording starts
     let wallpaper_config = validate_wallpaper_config(&settings, &api, win_id)?;
 
-    let force_natural = settings.natural();
     let should_generate_gif = !settings.video_only();
     let should_generate_video = settings.video() || settings.video_only();
     let (start_delay, end_delay, idle_pause) = (
         parse_delay(settings.start_pause.as_deref(), "start-pause")?,
         parse_delay(settings.end_pause.as_deref(), "end-pause")?,
         parse_delay(Some(settings.idle_pause()), "idle-pause")?,
     );
+    let fps = settings.fps();
 
     if should_generate_gif {
         check_for_gif()?;
@@ -130,19 +132,15 @@ fn main() -> Result<()> {
     let time_codes = Arc::new(Mutex::new(Vec::new()));
     let (tx, rx) = mpsc::channel();
     let photograph = {
-        let tempdir = tempdir.clone();
-        let time_codes = time_codes.clone();
-        thread::spawn(move || -> Result<()> {
-            capture_thread(
-                &rx,
-                api,
-                win_id,
-                time_codes,
-                tempdir,
-                force_natural,
-                idle_pause,
-            )
-        })
+        let ctx = CaptureContext {
+            win_id,
+            time_codes: time_codes.clone(),
+            tempdir: tempdir.clone(),
+            natural: settings.natural(),
+            idle_pause,
+            fps,
+        };
+        thread::spawn(move || -> Result<()> { capture_thread(&rx, api, ctx) })
     };
     let interact = thread::spawn(move || -> Result<()> { sub_shell_thread(&program).map(|_| ()) });
 
@@ -175,11 +173,11 @@ fn main() -> Result<()> {
         .unwrap()
         .context("Cannot launch the recording thread")?;
 
+    let frame_count = time_codes.lock().unwrap().borrow().len();
+    print_recording_summary(&settings, frame_count);
+
     println!();
-    println!(
-        "🎆 Applying effects to {} frames (might take a bit)",
-        time_codes.lock().unwrap().borrow().len()
-    );
+    println!("🎆 Applying effects (might take a bit)");
     show_tip();
 
     apply_big_sur_corner_effect(