video-use Event Listeners: Understanding the API Availability

video-use does not expose any event-listener API; it is a pure-Python utility library that operates through direct function calls rather than event-driven architecture.

The browser-use/video-use repository provides a collection of procedural helpers for video processing tasks such as frame extraction, audio envelope calculation, and timeline visualization. While developers familiar with HTML5 media players might expect event-listener patterns for handling playback events like play or pause, the library follows a fundamentally different approach that requires direct function invocation.

Why video-use Does Not Implement Event Listeners

According to the browser-use/video-use source code, the repository is designed as a pure-Python utility collection rather than an interactive media player. All core functionality lives in procedural helper modules that execute immediately when called, rather than waiting for runtime events.

Core Architecture: Procedural Python Functions

The library's functionality resides entirely in Python modules such as helpers/timeline_view.py, helpers/render.py, and helpers/transcribe.py. None of these modules define or register listeners for HTML-video events like play, pause, or timeupdate. Instead, users interact with the library by importing these modules and calling functions directly with specific parameters.

No JavaScript Front-End Component

Because video-use does not ship a JavaScript front-end component, there is no addEventListener method or similar registration function available. The library operates server-side or inPython scripts, processing video files through computational routines rather than responding to user interaction events in a browser environment.

Audio Events vs. Event Listeners

The only "event-like" concepts in the codebase are audio events that appear as structured data entries within transcripts. These are distinct from runtime event listeners.

Transcript Data Structure

In helpers/transcribe.py, audio events appear as data payloads with a specific type field (e.g., "type": "audio_event"). These entries represent segments of audio activity detected during transcription processing, stored as JSON data for later analysis. They are data classifications, not runtime callbacks or listeners that trigger code execution.

Working with video-use: Direct Function Calls

Since video-use event listeners do not exist, you interact with the library through explicit function calls. Below are the primary patterns for utilizing the core API.

Rendering Timeline Visualizations

To generate a composite timeline image showing video frames and transcript overlays, call render_timeline() directly from helpers/timeline_view.py:

from helpers.timeline_view import render_timeline
from pathlib import Path

render_timeline(
    video=Path("my_video.mp4"),
    start=12.5,
    end=17.0,
    out_path=Path("timeline.png"),
    n_frames=8,
    transcript=Path("my_transcript.json"),
)

Extracting Video Frames

To extract specific frames from a video segment, use the extract_frames() function:

from helpers.timeline_view import extract_frames
from pathlib import Path

frames = extract_frames(
    video=Path("my_video.mp4"),
    start=0,
    end=10,
    n=5,
    dest_dir=Path("tmp_frames")
)
print(frames)   # → list of Path objects for the extracted JPEGs

Key Source Files

The following modules collectively provide video-use functionality, but none expose a runtime event-listener interface:

• helpers/timeline_view.py – Core API for frame extraction, audio envelope computation, transcript overlay, and composite PNG rendering
• helpers/render.py – Low-level rendering utilities including font handling, color management, and image compositing
• helpers/transcribe.py – Transcript parsing and audio-event tagging functionality
• helpers/pack_transcripts.py – Transcript packaging and silence gap computation

Summary

• video-use does not expose event listeners; it is a procedural Python library, not an event-driven framework
• All functionality requires direct function calls to methods like render_timeline() and extract_frames()
• Audio events in helpers/transcribe.py are data payloads (e.g., "type": "audio_event"), not runtime callbacks
• The library lacks a JavaScript front-end, so there is no addEventListener equivalent
• Users seeking reactive media-player behavior must implement their own front-end event handling and call video-use functions when specific events fire

Frequently Asked Questions

Does video-use support HTML5 video events like play and pause?

No. video-use does not include a JavaScript runtime or HTML5 video player component. It is a server-side Python library for processing video files programmatically. If you need to react to play or pause events, you must implement that logic in your own front-end application and then invoke the appropriate video-use Python functions.

What are audio events in the video-use transcript files?

Audio events are data annotations stored in transcript JSON files processed by helpers/transcribe.py. They appear as dictionary entries with fields like "type": "audio_event" to mark segments of detected audio activity. These are static data labels used for timeline visualization, not dynamic event listeners that execute code.

How do I trigger actions when video processing completes?

Since video-use lacks an event system, you trigger actions by calling functions sequentially in your Python script. For example, call extract_frames() followed by render_timeline() in the same script execution flow. The functions return results immediately (such as file paths or processed data) that you can pass to subsequent operations.

Can I add custom event listeners to the video-use source code?

While you could theoretically wrap video-use functions in your own event-driven architecture, the library itself provides no hooks or extension points for event registration. The source code in helpers/timeline_view.py and related modules uses straightforward procedural programming. Any event-listener functionality would require building a custom wrapper or middleware layer on top of the existing function calls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}