FrameMark

FrameMark is a lightweight, frame-accurate video viewer for MP4 files built on top of mpv.

It provides a clean SMPTE-style timecode overlay (HH:MM:SS:FF), frame-by-frame navigation, live playback information, and one-click timecode copying. FrameMark is designed for video analysis, editing, sports review, VFX, and any workflow where frame accuracy matters.

---

Features

• Open MP4 videos directly
• SMPTE timecode overlay (HH:MM:SS:FF)
• Timecode displayed inside the video window
• Frame-by-frame navigation
• Exact one-second seeking
• Copy the current timecode to the clipboard
• Live terminal information
  • Current timecode
  • Total duration
  • Current frame
  • Total frame count
  • FPS
  • Play / Pause state
• Automatic FPS detection using ffprobe
• macOS support
• Linux support (X11 & Wayland)

---

Requirements

• mpv
• ffmpeg
• ffprobe

macOS

Install using Homebrew:

brew install mpv ffmpeg

Linux

Ubuntu / Debian

sudo apt install mpv ffmpeg xclip

or (Wayland)

sudo apt install mpv ffmpeg wl-clipboard

---

Installation

Clone the repository:

git clone https://github.com/DevMicroCore/FrameMark.git
cd FrameMark

Make the launcher executable:

chmod +x mp4_exact_time.sh

---

Usage

./mp4_exact_time.sh video.mp4

---

Keyboard Shortcuts

Key	Action
→	Next frame
←	Previous frame
↑	Seek forward 1 second
↓	Seek backward 1 second
Space	Play / Stop
C	Copy current timecode
Q	Quit

---

Terminal Output

Time: 00:00:02:23 / 00:00:26:14
Frame: 83 / 794
FPS: 30.000
Stop

---

Video Overlay

00:00:02:23 / 00:00:26:14

---

Project Structure

FrameMark/
├── mp4_exact_time.sh
├── timecode.lua
├── input.conf
└── README.md

---

How It Works

1. The launcher script reads the video's frame rate using ffprobe.
2. The frame rate is passed to the Lua script.
3. mpv starts playback.
4. The Lua script:
   • calculates SMPTE timecodes
   • draws the on-screen overlay
   • updates the terminal
   • copies timecodes to the clipboard
   • enables frame-accurate navigation

---

Roadmap

• Marker export
• CSV export
• Jump to frame number
• Jump to timecode
• Screenshot export
• Windows support