feat: add --idle-pause <time> to set the max time before idle frame optimization. Can improve readability. #267

ahundt · 2025-07-22T18:19:33Z

Add `--idle-pause <time>` the max time before idle frame optimization starts. Can improve readability.

This PR adds the --idle-pause parameter to t-rec's existing idle optimization. This parameter
allows users to specify a max duration for idle frames to be displayed before optimization
begins.

Benefits

The key benefit is giving viewers sufficient time to read the text on screen before the animation
advances to the next change. This makes demos easier to read and follow, particularly for:

Tutorials: Viewers can read command output at their own pace
Documentation: Step-by-step guides become more accessible
Educational Content: Learners have time to process information

Implementation Details

CLI Interface

Added -i, --idle-pause <s | ms | m> parameter
Uses the existing parse_delay function for duration parsing
Follows the same pattern as --start-pause and --end-pause

Core Logic Changes

Replaced the identical_frames counter with current_idle_period duration tracking
Frames are saved when current_idle_period < idle_pause threshold is met
Refactored frame comparison logic for cleaner boolean expressions
Added idle_pause: Option<Duration> parameter to capture_thread

Testing

Added integration test covering five scenarios: natural mode, first frame, different frames,
identical frames, and idle pause behavior
Uses conditional compilation for faster test execution (10ms vs 250ms intervals)
Uses mock API with minimal 1x1 RGBA pixel data for efficiency

Usage Examples

# Show 1 second of unchanged content before optimization
t-rec --idle-pause 1s

# Show 500ms of idle time
t-rec --idle-pause 500ms

# Original behavior (no idle pause)
t-rec

Backward Compatibility

When --idle-pause is not specified, behavior remains identical to previous versions.

Files Modified

src/cli.rs: Added CLI parameter definition
src/main.rs: Parses idle-pause argument and passes it to capture thread
src/capture.rs: Implements duration-based idle detection and test coverage
README.md: Documents parameter and provides usage examples

This enhancement extends t-rec's efficient idle optimization with user-configurable timing control,
enabling recordings to give viewers adequate reading time.

- Add -i/--idle-pause CLI parameter accepting duration values (s, ms, m) - Replace frame counting with duration-based idle detection - Allow specifying a minimum idle display time before optimization begins - Add test coverage with conditional compilation for faster execution - Update README documentation with usage examples Gives viewers time to read text on screen before the animation advances to the next change, making demos easier to follow.

…uration control Previous behavior: The idle_pause feature saved idle frames up to the threshold, then skipped the remaining idle frames. The skipped time remained in the timestamps, creating large gaps between consecutive frames during playback that exceeded the specified threshold (e.g., 10+ seconds instead of 3 seconds). What changed: - Refactored frame decision logic to maintain the timeline compression invariant - Modified idle frame handling to compress the timeline for skipped frames beyond the threshold - Preserved natural pauses up to the idle_pause duration while compressing excess time - Enhanced compression state tracking for smooth playback timing - Added comprehensive test coverage for multiple idle period scenarios Technical implementation: - Maintains compressed timestamps (effective_now = now - idle_duration) for all saved frames - Skips frames when current_idle_period >= threshold and adds duration to idle_duration - Preserves backward compatibility when idle_pause = None (maximum compression mode) - Timeline compression eliminates gaps preventing jarring playback issues Files affected: - src/capture.rs: Complete fix for idle period duration control with timeline compression - Updated capture_thread() function with corrected frame decision logic - Enhanced documentation explaining terminal recording quality goals - Added 9 comprehensive test cases covering edge cases and multiple idle periods Testable: Run capture tests to verify idle periods are compressed to exact threshold durations

… test Refactored capture module tests for better maintainability: - Merged 12 individual test functions into 1 table-driven test - Extracted reusable test infrastructure (TestApi, helper functions) - Replaced magic numbers with meaningful variable names - Added docstrings to all test functions and structs - Created frame sequence generation using simple number arrays - Improved test stability by allowing for timing variations - Made test descriptions more specific about expected behavior The single parameterized test runs all previous test scenarios through a test_cases array, reducing code duplication while maintaining the same test coverage. Files changed: - src/capture.rs: Consolidated test functions, added documentation

…ove documentation Previous behavior: Tests used create_frames() function with string patterns. Frame numbering and test format were undocumented. What changed: Removed create_frames() function and used inline test data arrays. Added documentation explaining that numbers represent pixel values simulating terminal activity. Made frames() generic. Documented the 5-element tuple format and [..] slice syntax. Why: Direct inline test data is clearer than string pattern matching. Documentation helps future maintainers understand the test framework. Files affected: - src/capture.rs: Simplified test structure and added comprehensive documentation Testable: cargo test test_idle_pause

Apply rustfmt to maintain consistent code style. Removes extra blank lines in documentation comments and reformats long function calls. Files affected: - src/capture.rs: Format documentation and function calls - src/main.rs: Reformat capture_thread call parameters

Previous behavior: Documentation contained vague terms, grammatical errors, and incorrectly stated files were saved as TGA format. What changed: - src/capture.rs: Fixed file format documentation (TGA → BMP) - Simplified verbose comments while preserving technical accuracy - Clarified how idle pause parameter controls frame compression - Fixed grammar issues throughout function and test documentation Why: Documentation must accurately describe code behavior and maintain clarity for future developers. Files affected: - src/capture.rs: Updated capture_thread() and test documentation

ahundt · 2025-07-25T19:37:58Z

I found and fixed a bug where some pauses wouldn't be clipped, I've fixed the issue and successfully tested it on a demo recording I've made. This is working really well now I have been using it for a while.

sassman · 2025-10-22T09:56:03Z

@ahundt I really like your idea, thank you so much for your contribution.

I'm thinking if it would not make sense to have something like 1s or 1.5s as a default that is always in place. Because it makes demos just way smoother, easier to follow.

What are your thoughts? Have you found a value that works best so far for you?

src/capture.rs

ahundt · 2025-10-23T18:29:18Z

Cool I'm glad you liked it! Thanks!

The time that's in there is the one I've been using but feel free to adjust it. It worked well for me as full pages were appearing between pauses in my case. I've been using it for a while now and I've been happy with it!

sassman · 2025-10-24T22:49:45Z

Just to be sure:

The time that's in there is the one I've been using

You are meaning this very 1s?

ahundt · 2025-10-25T04:52:20Z

I double checked, it turns out I settled on 3s for my demo script. YMMV though!

https://github.com/ahundt/pyuvstarter

src/capture.rs

sassman · 2025-10-25T07:55:29Z

Could you please have a look once more at the failing tests, that would be awesome to get them green.

ahundt added 2 commits July 22, 2025 14:05

feat: -i --idle-pause clearer help message in cli.rs README.md

11ad6ca

ahundt changed the title ~~feat: add --idle-pause <time> parameter for a minimum time before idle frame optimization starts to improve readability~~ feat: add --idle-pause <time> parameter sets a max time before idle frame optimization. Can improve readability. Jul 22, 2025

ahundt changed the title ~~feat: add --idle-pause <time> parameter sets a max time before idle frame optimization. Can improve readability.~~ feat: add --idle-pause <time> sets the max time before idle frame optimization. Can improve readability. Jul 22, 2025

ahundt changed the title ~~feat: add --idle-pause <time> sets the max time before idle frame optimization. Can improve readability.~~ feat: add --idle-pause <time> to set the max time before idle frame optimization. Can improve readability. Jul 22, 2025

ahundt added 5 commits July 25, 2025 12:44

sassman reviewed Oct 23, 2025

View reviewed changes

src/capture.rs Outdated Show resolved Hide resolved

chore: adjustment to trigger CI

086ea2e

Merge branch 'main' into feat/idle-pause-parameter

6843a34

sassman approved these changes Oct 24, 2025

View reviewed changes

sassman reviewed Oct 25, 2025

View reviewed changes

src/capture.rs Outdated Show resolved Hide resolved

fix formatting issue

bbc97a0

Merge branch 'main' into feat/idle-pause-parameter

7f09cc3

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: add --idle-pause <time> to set the max time before idle frame optimization. Can improve readability. #267

feat: add --idle-pause <time> to set the max time before idle frame optimization. Can improve readability. #267

ahundt commented Jul 22, 2025 •

edited

Loading

Uh oh!

ahundt commented Jul 25, 2025 •

edited

Loading

Uh oh!

sassman commented Oct 22, 2025

Uh oh!

Uh oh!

ahundt commented Oct 23, 2025 •

edited

Loading

Uh oh!

sassman commented Oct 24, 2025

Uh oh!

ahundt commented Oct 25, 2025 •

edited

Loading

Uh oh!

Uh oh!

sassman commented Oct 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

feat: add --idle-pause <time> to set the max time before idle frame optimization. Can improve readability. #267

Are you sure you want to change the base?

feat: add --idle-pause <time> to set the max time before idle frame optimization. Can improve readability. #267

Conversation

ahundt commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add --idle-pause <time> the max time before idle frame optimization starts. Can improve readability.

Benefits

Implementation Details

CLI Interface

Core Logic Changes

Testing

Usage Examples

Backward Compatibility

Files Modified

Uh oh!

ahundt commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sassman commented Oct 22, 2025

Uh oh!

Uh oh!

ahundt commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sassman commented Oct 24, 2025

Uh oh!

ahundt commented Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

sassman commented Oct 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ahundt commented Jul 22, 2025 •

edited

Loading

Add `--idle-pause <time>` the max time before idle frame optimization starts. Can improve readability.

ahundt commented Jul 25, 2025 •

edited

Loading

ahundt commented Oct 23, 2025 •

edited

Loading

ahundt commented Oct 25, 2025 •

edited

Loading