Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

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

wants to merge 7 commits into from
+393 −32

Conversation

ahundt
Copy link

@ahundt ahundt commented Jul 22, 2025 •
edited
Loading

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.

ahundt added 2 commits July 22, 2025 14:05
@ahundt
feat: add --idle-pause parameter for idle frame timing control
55a78e4 
- 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.
@ahundt
feat: -i --idle-pause clearer help message in cli.rs README.md
11ad6ca
@ahundt 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 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 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
@ahundt
fix(capture): correct idle period timeline compression for accurate d…
206d213 
…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
@ahundt
test(capture): consolidate idle pause tests into single parameterized…
21156ff 
… 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
@ahundt
test(capture): replace create_frames() with inline test data and impr…
439e82b 
…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
@ahundt
style(capture): apply cargo fmt formatting
6adbc16 
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
@ahundt
docs(capture): fix documentation accuracy and grammar
e799510 
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
Copy link
Author

ahundt commented Jul 25, 2025

I found 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@ahundt