clark

ABOUT a

• demo.mp4
• Trim and timestamp audio
• aka a TUI for interactive media playback, wrapped around mpv.

INSTALLATION a

pip install https://github.com/wong-justin/clark/archive/main.zip

REQUIREMENTS

• mpv
• python ~3.7?
• Optionally ffmpeg, for --trim and --split.

TROUBLESHOOTING

The most common errors are related to mpv installation, so check the docs for python-mpv.

USAGE a

CONTROLS

| Keypress      | Description                            |
|---------------|----------------------------------------|
|  space        | play/pause                             |
|  j/l          | -/+ 15 secs                            |
|  left/right   | -/+ 5 secs                             |
|  down/up      | -/+ speed x0.1                         |
|  0-9          | seek to 0,10,...90%                    |
|  m            | mark timestamp at curr position        |
|  M            | delete timestamp                       |
|  J/L          | seek to prev/next timestamp and pause  |
|  q/esc        | quit and print timestamps in millis    |
		

THE TUI, A BREAKDOWN

  position  duration  timestamp...idx/total
  ┌─┴──────────┴──────────┴─────────┴─┴─┐
  │ 43:19 / 1:26:44     52:06.438   3/6 │
  │ =================|                  ├──┐
  │       |      |       |    |   |     ├┐ │
  └─────────────────────────────────────┘│ │
                      timestamp markers  ┘ │
                                           │
     seekbar, playing (>) or paused (|)  ──┘
		

* Note: timestamps clustered together will appear under one marker. In this case, the total timestamp count will not match the number of markers on screen.

COMMAND-LINE OPTIONS

Usage:
  clark <filepath> [--trim | --split]
                   [--start-paused]
                   [--start-muted]
  clark (-h | --version)

Options:
  --trim          Extract between two timestamps
                  file.mp3 -> file_0.mp3
  --split         Cut at each timestamp
                  file.mp4 -> file_0.mp4, file_1.mp4, ...
  --start-paused  Disable autoplay
  --start-muted   Set volume to 0
  -h --help       Show this screen
  --version       Show version
		

* Note: The options --trim and --split are an alternative to piping timestamps into messy ffmpeg scripts. --trim and --split cannot be passed at the same time. Input files remain unmodified by these options.

EXAMPLES + RECIPES a

• Launch media player behind the terminal interface, mark some timestamps, and print them in milliseconds after quitting:

  clark audio.mp3

• Mark start and end points to trim away content from the ends of a video:

  clark video.mp4 --trim

• Choose where to split a concert recording into individual files, and don't autoplay:

  clark concert.mp3 --split --start-paused

• Use only audio from a video in order to avoid the GUI popup on start:

  ffmpeg -i video.mkv -map 0:a -acodec copy /tmp/audio.mp4; clark /tmp/audio.mp4

• Convert timestamps to HH:MM:SS:mmm:

  clark song.wav | awk '{system("date -u -d @" $0/1000 " +%T.%3N")}'

ROADMAP a

• Fix current timestamp not matching current seek position
• Catch SIGINT and gracefully close mpv process on interrupt
• Timestamp import option. clark --import 1000,2000,3000. Example use case: adjusting automated timestamps that are always a little inaccurate, even >1 second behind.
• If truly motivated: keep everything in the command-line by converting video to ANSI-color unicode blocks. Likely involves porting to high-performance language (rust + batimg?) and discarding MPV. Seems worthy of a separate project, even if it keeps the same features and interface.