SETUP GUIDE
How to Use WordPress TimeLapse Viewer for Design History — Step-by-Step Guide
A step-by-step walkthrough for activating the TimeLapse Viewer module, uploading your first session recording, browsing and searching sessions, using the video playback viewer with keyboard shortcuts, organizing sessions with tags, configuring settings, and integrating with the REST API.
Before You Start
What you will need
- A LuperIQ account with an active subscription.
- WordPress 6.0 or higher installed and running.
- LuperIQ installed on your WordPress site.
- Administrator access to your WordPress site (manage_options capability).
- A session recording to upload — this includes an MP4 video file, an optional thumbnail image (JPG), and an optional events CSV file with timestamped actions.
Step 1: Activate the TimeLapse Viewer Module
Go to your WordPress admin and navigate to LuperIQ Central in the left sidebar. Open the Modules tab and find TimeLapse Viewer in the Tools category. Click Activate. The module has no dependencies on other LuperIQ modules, so you can activate it independently.
On activation, the module creates two database tables: luperiq_timelapse_sessions for storing session metadata and video paths, and luperiq_timelapse_events for storing timestamped actions within each session. It also registers the luperiq_session custom post type and the luperiq_session_tag taxonomy. WordPress rewrite rules are flushed to ensure the new post type is accessible.
A new TimeLapse Viewer menu item appears in your WordPress admin sidebar with a video camera icon. It contains two pages: Sessions (the main session list) and Settings (module configuration). Click Sessions to open the main dashboard.
Step 2: Upload Your First Session Recording
Sessions are uploaded through the REST API endpoint at /wp-json/luperiq-timelapse/v1/upload. The upload accepts a multipart form request with up to three files and one required data field. The video field accepts an MP4 file of the session recording. The thumbnail field accepts a JPG image for the session preview. The events field accepts a CSV file containing timestamped event data. The session_data field is a required JSON string with the session ID, task name, start time, end time, duration in seconds, and optional report HTML and metadata.
To authenticate API requests, use WordPress Application Passwords. Go to your WordPress profile page (Users > Profile), scroll to the Application Passwords section, enter a name for the password (for example, TimeLapse Uploader), and click Add New Application Password. Copy the generated password. Use this password with your WordPress username in an HTTP Basic Authentication header when making upload requests.
When the upload succeeds, the module creates a directory under wp-content/uploads/luperiq-timelapse-sessions/ named after the session ID, saves the uploaded files there, inserts the session record into the database, imports events from the CSV, and creates a WordPress post of type luperiq_session. The API returns a 201 response with the new session ID and post ID. The session immediately appears in the Sessions list in your admin.
Step 3: Browse and Search Sessions
The Sessions page displays all active recordings in a WordPress list table. Each row shows the task name (linked to the detail view), duration in HH:MM:SS format, start time, end time, the display name of the user who uploaded it, and an action column with a View Video button that opens the MP4 in a new browser tab. The table is sorted by start time descending, so the most recent sessions appear first.
Use the search box at the top of the page to filter sessions by task name. The search field supports live debounce — after you stop typing for 500 milliseconds, the search executes automatically if you have entered at least 3 characters. You can also clear the search field and press Enter to reset the filter and show all sessions. The list paginates at 20 sessions per page with standard WordPress pagination controls.
To delete sessions, select them using the checkboxes in the first column. The checkbox in the table header selects or deselects all visible sessions. Choose Delete from the Bulk Actions dropdown and click Apply. A confirmation dialog asks you to verify before the deletion proceeds. You can also delete individual sessions by clicking the Delete link in the row actions below each task name.
Step 4: View a Session Recording
Click any task name in the Sessions list to open the session detail view. At the top, a Back to Sessions button returns you to the main list. Below that, a metadata table displays the session ID, duration, start time, end time, upload date, and the name of the user who uploaded the recording. This gives you the full context of when and by whom the session was created.
If the session has a video, it appears as an HTML5 video player with native browser controls for play, pause, volume, and fullscreen. The player is set to full width of the content area. Below the native controls, the TimeLapse Viewer adds enhanced playback controls: a speed selector dropdown with eight speeds from 0.25x to 3x, skip buttons for jumping 10 seconds forward or backward, and frame-by-frame stepping buttons that advance or rewind the video by 1/30th of a second. A time display below the controls shows the current position and total duration.
If the session includes an HTML report, it renders below the video player under a Report heading. If the session has events, they appear in a sortable table showing the timestamp, event type, and details for each action. The detail view displays up to 100 events. Sessions with more than 100 events show a note indicating the total count. Click any event row to seek the video to the corresponding moment in the recording.
Step 5: Use Keyboard Shortcuts for Playback
The session viewer registers seven keyboard shortcuts that work whenever the viewer is visible on the page. Press the spacebar to toggle between play and pause. Press the left arrow key to skip 5 seconds backward or the right arrow key to skip 5 seconds forward. Press the up arrow key to increase playback speed by 0.25x (maximum 4x) or the down arrow key to decrease speed by 0.25x (minimum 0.25x).
Press F to toggle fullscreen mode. The viewer supports the standard Fullscreen API, the WebKit-prefixed API for Safari, and the MS-prefixed API for older Edge versions. Press F again or Escape to exit fullscreen. Press M to toggle mute on and off. These shortcuts are scoped so they only fire when the viewer container is visible, preventing conflicts with other admin page interactions like typing in the search box.
For precision work, use the frame-step buttons in the control panel below the video. Each click advances or rewinds the video by 1/30th of a second (one frame at 30 fps). Combine this with the pause shortcut (spacebar) to freeze on a specific frame, then step forward or backward to find the exact moment a visual change occurred. The time display updates with each frame step so you can note the exact timestamp.
Step 6: Organize Sessions With Tags
The module registers a custom taxonomy called luperiq_session_tag that attaches to the luperiq_session post type. To add tags to a session, go to the WordPress post editor for that session's luperiq_session post. You can find these posts by navigating to the session detail view and noting the post ID, or by searching for the task name in the WordPress admin. Tags are non-hierarchical, so they work like standard WordPress post tags — type a tag name and press Enter to add it.
Use tags to organize sessions by project (Homepage Redesign, Q1 Sprint), by page (Header, Footer, Product Page), by client name, or by any other category that makes sense for your workflow. Tags appear as an admin column in the session post type listing, so you can sort and filter by tag. This is particularly useful when you have dozens or hundreds of sessions and need to find all recordings related to a specific project or component.
You can also manage session tags in bulk through the WordPress Quick Edit and Bulk Edit interfaces on the luperiq_session post list. Select multiple session posts, click Bulk Edit, add or remove tags, and click Update. This lets you retroactively organize existing sessions without opening each one individually.
Step 7: Configure Module Settings
Navigate to TimeLapse Viewer > Settings in your WordPress admin. The settings page has four configurable options. Auto-Delete After Days controls how long sessions are retained before automatic removal. Enter a number of days (for example, 90 for three months of retention) or set it to 0 to disable auto-deletion and keep all sessions indefinitely. Maximum Video Size (MB) sets the upper limit for uploaded video files. The default is 500 MB. Reduce this if your server has limited disk space or increase it for longer, higher-resolution recordings.
The Public Sharing checkbox enables shareable session URLs. When enabled, sessions can be accessed via a URL that does not require WordPress authentication. This is useful for sharing recordings with clients, stakeholders, or team members who do not have admin accounts. When disabled, all session access requires a logged-in user with manage_options capability. The Require Approval checkbox puts new uploads into a pending state. Uploaded sessions are not visible in the main list until an administrator reviews and approves them.
Below the settings form, the API Information section displays the REST API base URL and upload endpoint URL. Copy these into your recording tool or CI pipeline configuration. An Authentication section links to your WordPress profile page where you can generate Application Passwords. The Storage Information section shows the upload directory path and the total disk space used by all session recordings, calculated in real time by scanning the luperiq-timelapse-sessions directory.
Tips and Best Practices
Get the most from TimeLapse Viewer
- Name your sessions descriptively. The task_name field is the primary way you will search and identify sessions later. Use names like Homepage Hero Redesign v3 or Product Page Mobile Layout Fix rather than generic names like Session 1 or Test.
- Compress video files before uploading. MP4 files with H.264 encoding at a moderate bitrate provide good visual quality while keeping file sizes manageable. A 30-minute recording at 1080p with reasonable compression typically stays under 200 MB.
- Include events CSV files whenever possible. The event timeline adds significant value to recordings by letting viewers jump directly to specific actions instead of scrubbing through the entire video. Even a simple list of major milestones (layout changed, colors updated, content added) is more useful than no events at all.
- Use the auto-delete setting to manage storage on long-running projects. A 90-day retention window keeps recent sessions available while automatically cleaning up older recordings that are unlikely to be reviewed again.
- Tag sessions consistently. Establish a tagging convention with your team — project names, component names, sprint numbers — so that everyone can find related sessions quickly. Consistent tags make the archive searchable months later.
- Monitor storage usage on the Settings page. Video files accumulate quickly, especially with high-resolution recordings. Check the Storage Information section periodically and adjust your maximum file size or retention settings if disk usage is growing faster than expected.
- For automated pipelines, use the REST API list endpoint with date_from and date_to parameters to check whether a session for today's date already exists before uploading a duplicate.
Common Questions
The upload endpoint returns a 400 error with Invalid session data. What is wrong?
The session_data field must be a valid JSON string, not a raw object. Make sure you are sending it as a string field in the multipart form, not as a JSON body. The JSON must include at least session_id, task_name, and start_time fields. Check that your JSON is properly escaped if you are building it in a shell script.
I uploaded a session but it does not appear in the Sessions list.
Verify the upload returned a 201 status with a session_id in the response. If Require Approval is enabled in Settings, new sessions are in a pending state and will not appear in the active sessions list until approved. Also confirm you are logged in as an administrator — the Sessions page requires manage_options capability.
The video player shows a black screen but controls work.
The video file may be in a format or codec that your browser does not support. The module saves videos as timelapse.mp4 — ensure the source file uses the H.264 video codec and AAC audio codec in an MP4 container, which is universally supported by modern browsers. Re-encode the file with ffmpeg if needed: ffmpeg -i input.mkv -c:v libx264 -c:a aac output.mp4.
How do I migrate sessions to a different WordPress installation?
Export the luperiq_timelapse_sessions and luperiq_timelapse_events database tables, copy the wp-content/uploads/luperiq-timelapse-sessions/ directory to the new server, import the tables into the new database, and export/import the luperiq_session posts using the WordPress export tool. Update file paths in the sessions table if the WordPress installation path changed.
Keyboard shortcuts are not working on the session detail page.
Keyboard shortcuts fire only when the viewer container is visible on the page. If you are viewing the session through the standard admin detail view (not the JavaScript viewer), shortcuts may not be active. Click inside the video player area first to ensure the viewer has focus. Also verify that no browser extension is intercepting keyboard events.
Can I increase the events limit beyond 100 in the detail view?
The 100-event display limit is set in the SessionsPage.php template using array_slice. All events are loaded from the database — only the display is capped. You can modify the template file to increase or remove this limit, but be aware that sessions with thousands of events may slow down the admin page rendering.
Start Recording Your WordPress Design History Today
Activate TimeLapse Viewer, upload your first session recording, and play it back with variable-speed controls and event timelines. Every design change preserved, searchable, and replayable — directly inside your WordPress admin.