videogrep

If you do not have subtitle files, you can generate transcriptions using the --transcribe flag. This uses the vosk engine and generates a .json file in the same directory as the input. By default, it uses the Vosk small English model.

You can specify a custom Vosk model using the --model flag.

Videogrep is compatible with Python 3.6 to 3.10. To install the core tool, use pip install videogrep. If you need to transcribe video or audio files (rather than using existing subtitle tracks), you must also install vosk separately.

pip install videogrep
pip install vosk

The most basic way to use Videogrep is to provide an input file and a search phrase. The search phrase supports regular expressions.

Important Requirement: Videogrep requires a matching subtitle track (.srt or .vtt) or a transcription file (.json) for the input file. The subtitle file must have the exact same name as the media file, differing only by the extension (e.g., movie.mp4 and movie.srt).

videogrep --input path/to/video.mp4 --search 'search phrase'

The transcribe function converts the audio from a video file into a list of timestamped text segments using the Vosk speech recognition engine.

Behavioral Notes:

• Caching: If a .json file with the same name as the video exists in the same directory, the function will load and return that cached transcript instead of re-processing the video.
• Output Format: Returns a List[dict]. Each dictionary contains:
  • content: A string of the transcribed text (capped at MAX_CHARS, which is 36).
  • start: The start timestamp of the segment.
  • end: The end timestamp of the segment.
  • words: A list of individual word objects containing detailed metadata (e.g., word, start, end).
• Dependencies: Requires vosk and imageio_ffmpeg to be installed. It uses ffmpeg internally to extract audio at a 16000Hz sample rate.

Generates n-grams from the transcripts of one or more video files.

Parameters:

• files: A single file path or a list of file paths.
• n: The size of the n-gram (default is 1).

Returns: An iterator of tuples containing the n-gram and its occurrences.

Uses pocketsphinx_continuous to transcribe the audio from a video file.

Workflow:

1. Checks if a .transcript file already exists for the input file; if so, returns its content.
2. If not, converts the video to a temporary WAV file using convert_to_wav.
3. Runs pocketsphinx_continuous with the -time yes flag to include timestamps.
4. Saves the resulting transcription to a .transcript file.
5. Cleans up the temporary WAV file.

Requirements:

• ffmpeg must be installed and available in the system path.
• pocketsphinx_continuous must be installed and available in the system path.

These utility functions allow for fine-tuning the list of segments (timestamps) before exporting.

• remove_overlaps(segments): Sorts segments by start time and merges any segments that overlap in time.
• pad_and_sync(segments, padding=0, resync=0):
  • padding: Adds time to both the start and end of each segment.
  • resync: Shifts the entire segment (start and end) by a specified offset.
  • Also handles merging overlapping segments that belong to the same file.

Input Format: segments should be a List[dict] where each dict contains {'start': float, 'end': float, 'file': str}.

The search() function finds timestamps in video files based on a query. It supports three search modes:

• sentence: Matches the query against the full content of a transcript line using regular expressions.
• fragment: Matches a sequence of words (a phrase) by looking for word-level timestamps. This requires the transcript to have word-level data.
• mash: Finds random occurrences of specific words from the query.

Returns a list of dictionaries in the format: [{'file': str, 'start': float, 'end': float, 'content': str}].

Parameters:

• files: A single file path or a list of file paths.
• query: A single regex string or a list of queries.
• search_type: One of "sentence", "fragment", or "mash".
• prefer: (Optional) Preferred transcript file type (vtt, srt, or json).