A streamlined interface for precise video control and screenshot capture
with VLC media player on Linux systems, built on the
`chloop <https://github.com/kenjyco/chloop>`__ REPL framework. This
library provides D-Bus integration for real-time VLC control and
vim-style keyboard navigation designed for interactive video analysis
and content review workflows.
**Linux-only requirements:** This library uses D-Bus for VLC
communication, ImageMagick for screenshot capture, and ``wmctrl`` for
window management, making it compatible with Linux desktop environments
only.
The core philosophy emphasizes **precision and workflow optimization**
for users who need frame-accurate video navigation, timestamped
screenshot capture, and immediate keyboard control during active video
review. Rather than wrestling with VLC’s complex interface during
detailed video work, vlc-helper reduces cognitive overhead by providing
instant keyboard shortcuts and direct player control for essential
playback functions.
**Who benefits from this library:** - Video editors and content creators
reviewing footage frame-by-frame - Researchers analyzing video content
with precise timestamp requirements - Educators creating timestamped
video materials and screenshots - Quality assurance professionals
testing video applications - Content reviewers needing rapid navigation
and screenshot workflows - Anyone requiring precise video navigation
during active viewing sessions
Install
-------
Install system requirements for ``dbus-python`` package
::
sudo apt-get install -y pkg-config libdbus-1-dev libdbus-glib-1-dev
Install with ``pip``
::
pip install vlc-helper
QuickStart
----------
The ``vlc-repl`` and ``myvlc`` scripts are provided.
.. code:: bash
# Start VLC with precise timestamp control
myvlc video.mp4 "1h23m45s" "1h25m30s" # Play from 1:23:45 to 1:25:30
# Or start the interactive controller for any running VLC
vlc-repl
**Interactive Controls:** - ``space`` - pause/unpause - ``s`` - take
screenshot with timestamp in filename - ``i`` - show current file info
and position - ``h``/``l`` - seek backward/forward (5 seconds) -
``H``/``L`` - seek backward/forward (30 seconds) - ``←``/``→`` - seek
backward/forward (1 second, arrow keys) - ``n``/``p`` - next/previous
file in playlist - ``K`` - kill all VLC processes
**Colon Commands:** - ``:seek 15`` - seek forward 15 seconds -
``:go 1h23m45s`` - jump to specific timestamp
**What you gain:** Transform VLC from a general media player into a
precision video analysis tool during active viewing. Capture perfectly
timestamped screenshots, navigate to exact moments with single
keystrokes, and maintain focus on content analysis rather than interface
navigation. Essential for workflows requiring frame-accurate video
review.
API Overview
------------
High-Level Video Control
~~~~~~~~~~~~~~~~~~~~~~~~
Interactive REPL Interface
^^^^^^^^^^^^^^^^^^^^^^^^^^
- **``repl``** - Pre-configured interactive controller for running VLC
instances
- Inherits from GetCharLoop for single-keystroke efficiency
- ``chfunc_dict``: Ordered dictionary mapping keys to VLC control
functions
- ``name``: Collection name for logging (‘vlc’)
- ``prompt``: Display prompt (‘vlc-repl>’)
- Returns: Interactive video control session
- Internal calls: GetCharLoop.__init__, VLC() instance methods
Precise Video Launching
^^^^^^^^^^^^^^^^^^^^^^^
- **``vlcstart_precise(filename='', starttime='', stoptime='', background=False)``**
- Launch VLC with exact timing control
- ``filename``: Video file path (supports ~ expansion and relative
paths)
- ``starttime``: Start timestamp in formats like ‘1h23m45s’,
‘2:15:30’, ‘300s’
- ``stoptime``: Optional end timestamp (VLC stops playback
automatically)
- ``background``: If True, launch without blocking using
SimpleBackgroundTask
- Returns: None (launches VLC process for interactive control)
- Internal calls: ih.timestamp_to_seconds, SimpleBackgroundTask
- **``play_many(*filenames, background=False)``** - Launch VLC with
multiple files in playlist
- ``*filenames``: Multiple video file paths
- ``background``: If True, launch without blocking
- Returns: None (launches VLC with playlist for interactive control)
- Internal calls: SimpleBackgroundTask
VLC Player Control
~~~~~~~~~~~~~~~~~~
VLC Class - D-Bus Interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- **``VLC()``** - D-Bus interface for controlling running VLC player
instances
- Auto-connects to VLC via MPRIS (Media Player Remote Interfacing
Specification)
- Handles connection failures with automatic VLC startup and
reconnection
- Returns: VLC control object with real-time playback and metadata
access
- Internal calls: vlcstart_precise()
Playback State Management
^^^^^^^^^^^^^^^^^^^^^^^^^
- **``VLC.toggle_pause()``** - Toggle play/pause state
- Returns: None (changes playback state immediately)
- Internal calls: None
- **``VLC.next()``** - Skip to next file in playlist
- Returns: None (advances to next track)
- Internal calls: None
- **``VLC.previous()``** - Skip to previous file in playlist
- Returns: None (goes to previous track)
- Internal calls: None
Navigation and Seeking
^^^^^^^^^^^^^^^^^^^^^^
- **``VLC.seek(val)``** - Relative seeking forward or backward
- ``val``: Number of seconds (positive=forward, negative=backward)
- Returns: None (updates playback position instantly)
- Internal calls: None
- **``VLC.go(timestamp)``** - Jump to absolute position in video
- ``timestamp``: Target time in formats like ‘1h23m45s’, ‘2:15:30’,
‘300s’
- Returns: None (seeks to exact position)
- Internal calls: ih.timestamp_to_seconds, VLC.seek()
Video Information and Metadata
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- **``VLC.position``** (property) - Current playback position in
seconds
- Returns: Float representing current video position
- Internal calls: None
- **``VLC.filename``** (property) - Current video filename without path
- Returns: String basename of currently playing file
- Internal calls: None
- **``VLC.dirname``** (property) - Directory path of current video
- Returns: String directory path (handles file:// URLs)
- Internal calls: None
- **``VLC.window_title``** (property) - VLC window title for external
tool targeting
- Returns: String window title suitable for ImageMagick import
command (uses wmctrl)
- Internal calls: None
- **``VLC.info``** (property) - Combined metadata dictionary
- Returns: Dict with ‘filename’, ‘dirname’, ‘position’,
‘window_title’
- Internal calls: VLC.position, VLC.filename, VLC.dirname,
VLC.window_title
- **``VLC.show_info(fmt='{position} {dirname}/{filename}')``** -
Display formatted video information
- ``fmt``: Format string template for display
- Returns: None (prints current video state)
- Internal calls: VLC.info
Screenshot Capture
^^^^^^^^^^^^^^^^^^
- **``VLC.screenshot()``** - Capture current frame with timestamped
filename
- Returns: None (saves PNG with format:
screenshot–filename–timestamp.png using ImageMagick)
- Internal calls: VLC._screenshot(), SimpleBackgroundTask
- **``VLC.killall()``** - Force terminate all VLC processes
- Returns: None (kills processes with escalating signals)
- Internal calls: None
REPL Interactive Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~
REPL Class - Interactive Controller
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- **``REPL(chfunc_dict, name='vlc', prompt='vlc-repl> ')``** -
Interactive video controller with vim-style keybindings
- ``chfunc_dict``: Ordered dictionary mapping keys to VLC control
functions
- ``name``: Collection name for logging
- ``prompt``: Display prompt
- Inherits from GetCharLoop for single-keystroke efficiency
- Returns: Interactive video control session
- Internal calls: GetCharLoop.__init_\_
REPL Command Methods
^^^^^^^^^^^^^^^^^^^^
- **``REPL.seek(num)``** - Seek by specified number of seconds (colon
command)
- ``num``: Seconds to seek (string converted to float)
- Returns: None (calls VLC.seek for immediate response)
- Internal calls: VLC.seek()
- **``REPL.go(timestamp)``** - Jump to specific timestamp (colon
command)
- ``timestamp``: Target time in supported formats
- Returns: None (calls VLC.go for precise navigation)
- Internal calls: VLC.go()
Raw data
{
"_id": null,
"home_page": "https://github.com/kenjyco/vlc-helper",
"name": "vlc-helper",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "vlc, video, video player, cli, command-line, repl, dbus, screenshots, annotations, helper, kenjyco",
"author": "Ken",
"author_email": "kenjyco@gmail.com",
"download_url": "https://github.com/kenjyco/vlc-helper/tarball/v0.1.9",
"platform": null,
"description": "A streamlined interface for precise video control and screenshot capture\nwith VLC media player on Linux systems, built on the\n`chloop <https://github.com/kenjyco/chloop>`__ REPL framework. This\nlibrary provides D-Bus integration for real-time VLC control and\nvim-style keyboard navigation designed for interactive video analysis\nand content review workflows.\n\n**Linux-only requirements:** This library uses D-Bus for VLC\ncommunication, ImageMagick for screenshot capture, and ``wmctrl`` for\nwindow management, making it compatible with Linux desktop environments\nonly.\n\nThe core philosophy emphasizes **precision and workflow optimization**\nfor users who need frame-accurate video navigation, timestamped\nscreenshot capture, and immediate keyboard control during active video\nreview. Rather than wrestling with VLC\u2019s complex interface during\ndetailed video work, vlc-helper reduces cognitive overhead by providing\ninstant keyboard shortcuts and direct player control for essential\nplayback functions.\n\n**Who benefits from this library:** - Video editors and content creators\nreviewing footage frame-by-frame - Researchers analyzing video content\nwith precise timestamp requirements - Educators creating timestamped\nvideo materials and screenshots - Quality assurance professionals\ntesting video applications - Content reviewers needing rapid navigation\nand screenshot workflows - Anyone requiring precise video navigation\nduring active viewing sessions\n\nInstall\n-------\n\nInstall system requirements for ``dbus-python`` package\n\n::\n\n sudo apt-get install -y pkg-config libdbus-1-dev libdbus-glib-1-dev\n\nInstall with ``pip``\n\n::\n\n pip install vlc-helper\n\nQuickStart\n----------\n\nThe ``vlc-repl`` and ``myvlc`` scripts are provided.\n\n.. code:: bash\n\n # Start VLC with precise timestamp control\n myvlc video.mp4 \"1h23m45s\" \"1h25m30s\" # Play from 1:23:45 to 1:25:30\n\n # Or start the interactive controller for any running VLC\n vlc-repl\n\n**Interactive Controls:** - ``space`` - pause/unpause - ``s`` - take\nscreenshot with timestamp in filename - ``i`` - show current file info\nand position - ``h``/``l`` - seek backward/forward (5 seconds) -\n``H``/``L`` - seek backward/forward (30 seconds) - ``\u2190``/``\u2192`` - seek\nbackward/forward (1 second, arrow keys) - ``n``/``p`` - next/previous\nfile in playlist - ``K`` - kill all VLC processes\n\n**Colon Commands:** - ``:seek 15`` - seek forward 15 seconds -\n``:go 1h23m45s`` - jump to specific timestamp\n\n**What you gain:** Transform VLC from a general media player into a\nprecision video analysis tool during active viewing. Capture perfectly\ntimestamped screenshots, navigate to exact moments with single\nkeystrokes, and maintain focus on content analysis rather than interface\nnavigation. Essential for workflows requiring frame-accurate video\nreview.\n\nAPI Overview\n------------\n\nHigh-Level Video Control\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nInteractive REPL Interface\n^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- **``repl``** - Pre-configured interactive controller for running VLC\n instances\n\n - Inherits from GetCharLoop for single-keystroke efficiency\n - ``chfunc_dict``: Ordered dictionary mapping keys to VLC control\n functions\n - ``name``: Collection name for logging (\u2018vlc\u2019)\n - ``prompt``: Display prompt (\u2018vlc-repl>\u2019)\n - Returns: Interactive video control session\n - Internal calls: GetCharLoop.__init__, VLC() instance methods\n\nPrecise Video Launching\n^^^^^^^^^^^^^^^^^^^^^^^\n\n- **``vlcstart_precise(filename='', starttime='', stoptime='', background=False)``**\n - Launch VLC with exact timing control\n\n - ``filename``: Video file path (supports ~ expansion and relative\n paths)\n - ``starttime``: Start timestamp in formats like \u20181h23m45s\u2019,\n \u20182:15:30\u2019, \u2018300s\u2019\n - ``stoptime``: Optional end timestamp (VLC stops playback\n automatically)\n - ``background``: If True, launch without blocking using\n SimpleBackgroundTask\n - Returns: None (launches VLC process for interactive control)\n - Internal calls: ih.timestamp_to_seconds, SimpleBackgroundTask\n\n- **``play_many(*filenames, background=False)``** - Launch VLC with\n multiple files in playlist\n\n - ``*filenames``: Multiple video file paths\n - ``background``: If True, launch without blocking\n - Returns: None (launches VLC with playlist for interactive control)\n - Internal calls: SimpleBackgroundTask\n\nVLC Player Control\n~~~~~~~~~~~~~~~~~~\n\nVLC Class - D-Bus Interface\n^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- **``VLC()``** - D-Bus interface for controlling running VLC player\n instances\n\n - Auto-connects to VLC via MPRIS (Media Player Remote Interfacing\n Specification)\n - Handles connection failures with automatic VLC startup and\n reconnection\n - Returns: VLC control object with real-time playback and metadata\n access\n - Internal calls: vlcstart_precise()\n\nPlayback State Management\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- **``VLC.toggle_pause()``** - Toggle play/pause state\n\n - Returns: None (changes playback state immediately)\n - Internal calls: None\n\n- **``VLC.next()``** - Skip to next file in playlist\n\n - Returns: None (advances to next track)\n - Internal calls: None\n\n- **``VLC.previous()``** - Skip to previous file in playlist\n\n - Returns: None (goes to previous track)\n - Internal calls: None\n\nNavigation and Seeking\n^^^^^^^^^^^^^^^^^^^^^^\n\n- **``VLC.seek(val)``** - Relative seeking forward or backward\n\n - ``val``: Number of seconds (positive=forward, negative=backward)\n - Returns: None (updates playback position instantly)\n - Internal calls: None\n\n- **``VLC.go(timestamp)``** - Jump to absolute position in video\n\n - ``timestamp``: Target time in formats like \u20181h23m45s\u2019, \u20182:15:30\u2019,\n \u2018300s\u2019\n - Returns: None (seeks to exact position)\n - Internal calls: ih.timestamp_to_seconds, VLC.seek()\n\nVideo Information and Metadata\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- **``VLC.position``** (property) - Current playback position in\n seconds\n\n - Returns: Float representing current video position\n - Internal calls: None\n\n- **``VLC.filename``** (property) - Current video filename without path\n\n - Returns: String basename of currently playing file\n - Internal calls: None\n\n- **``VLC.dirname``** (property) - Directory path of current video\n\n - Returns: String directory path (handles file:// URLs)\n - Internal calls: None\n\n- **``VLC.window_title``** (property) - VLC window title for external\n tool targeting\n\n - Returns: String window title suitable for ImageMagick import\n command (uses wmctrl)\n - Internal calls: None\n\n- **``VLC.info``** (property) - Combined metadata dictionary\n\n - Returns: Dict with \u2018filename\u2019, \u2018dirname\u2019, \u2018position\u2019,\n \u2018window_title\u2019\n - Internal calls: VLC.position, VLC.filename, VLC.dirname,\n VLC.window_title\n\n- **``VLC.show_info(fmt='{position} {dirname}/{filename}')``** -\n Display formatted video information\n\n - ``fmt``: Format string template for display\n - Returns: None (prints current video state)\n - Internal calls: VLC.info\n\nScreenshot Capture\n^^^^^^^^^^^^^^^^^^\n\n- **``VLC.screenshot()``** - Capture current frame with timestamped\n filename\n\n - Returns: None (saves PNG with format:\n screenshot\u2013filename\u2013timestamp.png using ImageMagick)\n - Internal calls: VLC._screenshot(), SimpleBackgroundTask\n\n- **``VLC.killall()``** - Force terminate all VLC processes\n\n - Returns: None (kills processes with escalating signals)\n - Internal calls: None\n\nREPL Interactive Interface\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nREPL Class - Interactive Controller\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- **``REPL(chfunc_dict, name='vlc', prompt='vlc-repl> ')``** -\n Interactive video controller with vim-style keybindings\n\n - ``chfunc_dict``: Ordered dictionary mapping keys to VLC control\n functions\n - ``name``: Collection name for logging\n - ``prompt``: Display prompt\n - Inherits from GetCharLoop for single-keystroke efficiency\n - Returns: Interactive video control session\n - Internal calls: GetCharLoop.__init_\\_\n\nREPL Command Methods\n^^^^^^^^^^^^^^^^^^^^\n\n- **``REPL.seek(num)``** - Seek by specified number of seconds (colon\n command)\n\n - ``num``: Seconds to seek (string converted to float)\n - Returns: None (calls VLC.seek for immediate response)\n - Internal calls: VLC.seek()\n\n- **``REPL.go(timestamp)``** - Jump to specific timestamp (colon\n command)\n\n - ``timestamp``: Target time in supported formats\n - Returns: None (calls VLC.go for precise navigation)\n - Internal calls: VLC.go()\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CLI helpers for VLC media player",
"version": "0.1.9",
"project_urls": {
"Download": "https://github.com/kenjyco/vlc-helper/tarball/v0.1.9",
"Homepage": "https://github.com/kenjyco/vlc-helper"
},
"split_keywords": [
"vlc",
" video",
" video player",
" cli",
" command-line",
" repl",
" dbus",
" screenshots",
" annotations",
" helper",
" kenjyco"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1af5e2d6e72f031f4a37e7ea34fb5133a7d3076abc583ac342eac1949fc8c09d",
"md5": "1fe513c1763eaa2ca8f6d05753327cd9",
"sha256": "ec96a5dc46893df96d146c19f21f012699066fd5c0b7b4d392df0c933d978332"
},
"downloads": -1,
"filename": "vlc_helper-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1fe513c1763eaa2ca8f6d05753327cd9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9440,
"upload_time": "2025-07-23T18:34:44",
"upload_time_iso_8601": "2025-07-23T18:34:44.340783Z",
"url": "https://files.pythonhosted.org/packages/1a/f5/e2d6e72f031f4a37e7ea34fb5133a7d3076abc583ac342eac1949fc8c09d/vlc_helper-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 18:34:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kenjyco",
"github_project": "vlc-helper",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "bg-helper",
"specs": []
},
{
"name": "chloop",
"specs": []
},
{
"name": "click",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "dbus-python",
"specs": []
}
],
"lcname": "vlc-helper"
}
JSON
