{"id":13412242,"url":"https://github.com/antiboredom/videogrep","last_synced_at":"2025-04-10T23:25:42.787Z","repository":{"id":17433290,"uuid":"20206631","full_name":"antiboredom/videogrep","owner":"antiboredom","description":"automatic video supercuts with python","archived":false,"fork":false,"pushed_at":"2024-04-19T00:22:25.000Z","size":42616,"stargazers_count":3389,"open_issues_count":18,"forks_count":259,"subscribers_count":84,"default_branch":"master","last_synced_at":"2025-04-03T11:57:08.574Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://antiboredom.github.io/videogrep","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antiboredom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-05-27T04:11:50.000Z","updated_at":"2025-04-03T10:58:28.000Z","dependencies_parsed_at":"2023-01-14T00:15:15.073Z","dependency_job_id":"b27e6e95-4294-4b53-aea1-c7578779587b","html_url":"https://github.com/antiboredom/videogrep","commit_stats":{"total_commits":181,"total_committers":19,"mean_commits":9.526315789473685,"dds":0.3149171270718232,"last_synced_commit":"e0ed0388f4391de5a26bc0941a32d7679ac9e502"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antiboredom%2Fvideogrep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antiboredom%2Fvideogrep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antiboredom%2Fvideogrep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antiboredom%2Fvideogrep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antiboredom","download_url":"https://codeload.github.com/antiboredom/videogrep/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248313746,"owners_count":21082907,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T20:01:22.526Z","updated_at":"2025-04-10T23:25:42.758Z","avatar_url":"https://github.com/antiboredom.png","language":"Python","funding_links":[],"categories":["Python","HarmonyOS","📦 Legacy \u0026 Inactive Projects","Media Tools"],"sub_categories":["Windows Manager","Batch Processing \u0026 Automation"],"readme":"Videogrep\n=========\n\nVideogrep is a command line tool that searches through dialog in video or audio files and makes supercuts based on what it finds. It will recognize `.srt` or `.vtt` subtitle tracks, or transcriptions that can be generated with vosk, pocketsphinx, and other tools.\n\n#### Examples\n\n* [The Meta Experience](https://www.youtube.com/watch?v=nGHbOckpifw)\n* [All the instances of the phrase \"time\" in the movie \"In Time\"](https://www.youtube.com/watch?v=PQMzOUeprlk)\n* [All the one to two second silences in \"Total Recall\"](https://www.youtube.com/watch?v=qEtEbXVbYJQ)\n* [A former press secretary telling us what he can tell us](https://www.youtube.com/watch?v=D7pymdCU5NQ)\n\n#### Tutorial\n\nSee my blog for a short [tutorial on videogrep and yt-dlp](https://lav.io/notes/videogrep-tutorial/), and part 2, on [videogrep and natural language processing](https://lav.io/notes/videogrep-and-spacy/).\n\n----\n\n## Installation\n\nVideogrep is compatible with Python versions 3.6 to 3.10.\n\nTo install:\n\n```\npip install videogrep\n```\n\nIf you want to transcribe video or audio, you also need to install [vosk](https://alphacephei.com/vosk/):\n\n```\npip install vosk\n```\n\nNote: the previous version of videogrep supported pocketsphinx for speech-to-text. Vosk seems *much* better so I've added support for it and will likely be phasing out support for pocketsphinx.\n\n## Usage\n\nThe most basic use:\n\n```\nvideogrep --input path/to/video.mp4 --search 'search phrase'\n```\n\nIt works with audio too:\n```\nvideogrep --input path/to/audio.mp3 --search 'search phrase'\n```\n\nYou can put any regular expression in the search phrase.\n\n**NOTE: videogrep requires a matching subtitle track with each video you want to use. The video/audio file and subtitle file need to have the exact same name, up to the extension.** For example, `my_movie.mp4` and `my_movie.srt` will work, and `my_movie.mp4` and `my_movie_subtitle.srt` will *not* work.\n\nVideogrep will search for matching `srt` and `vtt` subtitles, as well as `json` transcript files that can be generated with the `--transcribe` argument.\n\n### Options\n\n#### `--input [filename(s)] / -i [filename(s)]`\n\nFile or files to use as input. Most video or audio formats should work. If you mix audio and video input files, the resulting output will only be audio.\n\n\n#### `--output [filename] / -o [filename]`\n\nName of the file to generate. By default this is `supercut.mp4`. Any standard video or audio extension will also work. (If you're using audio input or mixed audio and video input and you keep the default `supercut.mp4` as the output filename, videogrep will automatically change the output to `supercut.mp3`)\n\nVideogrep will also recognize the following extensions for saving files:\n  * `.mpv.edl`: generates an edl file playable by [mpv](https://mpv.io/) (useful for previews)\n  * `.m3u`: media playlist\n  * `.xml`: Final Cut Pro timeline, compatible with Adobe Premiere and Davinci Resolve\n\n```\nvideogrep --input path/to/video --search 'search phrase' --output coolvid.mp4\n```\n\n\n#### `--search [query] / -s [query]`\n\nSearch term, as a regular expression. You can add as many of these as you want. For example:\n\n```\nvideogrep --input path/to/video --search 'search phrase' --search 'another search' --search 'a third search' --output coolvid.mp4\n```\n\n\n#### `--search-type [type] / -st [type]`\n\nType of search you want to perform. There are two options:\n\n* `sentence`: (default): Generates clips containing the full sentences of your search query.\n* `fragment`: Generates clips containing the exact word or phrase of your search query.\n\nBoth options take regular expressions. You may only use the `fragment` search if your transcript has word-level timestamps, which will be the case for youtube `.vtt` files, or if you generated a transcript using Videogrep itself.\n\n```\nvideogrep --input path/to/video --search 'experience' --search-type fragment\n```\n\n#### `--max-clips [num] / -m [num]`\n\nMaximum number of clips to use for the supercut.\n\n\n#### `--demo / -d`\n\nShow the search results without making the supercut.\n\n#### `--preview / -pr`\n\nPreview the supercut in mpv (requires [mpv to be installed](https://mpv.io/))\n\n#### `--randomize / -r`\n\nRandomize the order of the clips.\n\n\n#### `--padding [seconds] / -p [seconds]`\n\nPadding in seconds to add to the start and end of each clip.\n\n#### `--resyncsubs [seconds] / -rs [seconds]`\n\nTime in seconds to shift the shift the subtitles forwards or backwards.\n\n#### `--transcribe / -tr`\n\nTranscribe the video/audio using [vosk](https://alphacephei.com/vosk/). This will generate a `.json` file in the same folder as the video. By default this uses vosk's small english model.\n\n**NOTE:** Because of some compatibility issues, vosk must be installed separately with `pip install vosk`.\n\n```\nvideogrep -i vid.mp4 --transcribe\n```\n\n#### `--model [modelpath] / -mo [modelpath]`\n\nIn combination with the `--transcribe` option, allows you to specify the path to a vosk model folder to use. Vosk models are [available here](https://alphacephei.com/vosk/models) in a variety of languages.\n\n```\nvideogrep -i vid.mp4 --transcribe --model path/to/model/\n```\n\n#### `--export-clips / -ec`\n\nExports clips as individual files rather than as a supercut.\n\n```\nvideogrep -i vid.mp4 --search 'whatever' --export-clips\n```\n\n#### `--export-vtt / -ev`\n\nExports the transcript of the supercut as a WebVTT file next to the video.\n\n```\nvideogrep -i vid.mp4 --search 'whatever' --export-vtt\n```\n\n#### `--ngrams [num] / -n [num]`\n\nShows common words and phrases from the video or audio file.\n\n```\nvideogrep -i vid.mp4 --ngrams 1\n```\n\n\n----\n\n\n## Use it as a module\n\n```\nfrom videogrep import videogrep\n\nvideogrep('path/to/your/files','output_file_name.mp4', 'search_term', 'search_type')\n```\nThe videogrep module accepts the same parameters as the command line script. To see the usage check out the source.\n\n### Example Scripts\n\nAlso see the examples folder for:\n* [silence extraction](https://github.com/antiboredom/videogrep/blob/master/examples/only_silence.py)\n* [automatically creating supercuts](https://github.com/antiboredom/videogrep/blob/master/examples/auto_supercut.py)\n* [creating supercuts based on youtube searches](https://github.com/antiboredom/videogrep/blob/master/examples/auto_youtube.py)\n* [creating supercuts from specific parts of speech](https://github.com/antiboredom/videogrep/blob/master/examples/parts_of_speech.py)\n* [creating supercuts from spacy pattern matching](https://github.com/antiboredom/videogrep/blob/master/examples/pattern_matcher.py)\n\n----\n\n## Credits\n\nVideogrep is maintained by [Sam Lavigne](https://lav.io), and built using [MoviePy](https://zulko.github.io/moviepy/) and [Vosk](https://alphacephei.com/vosk/). A big thanks goes out to all those who have [contributed](https://github.com/antiboredom/videogrep/graphs/contributors), particuarly to [Charlie Macquarie](https://charliemacquarie.com) for his efforts in getting the project to work with audio-only media.\n\nVideogrep has received financial support from the [Department of Digital Humanities, King’s College London](https://www.kcl.ac.uk/ddh) and from the [Clinic for Open Source Arts](https://clinicopensourcearts.org/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantiboredom%2Fvideogrep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantiboredom%2Fvideogrep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantiboredom%2Fvideogrep/lists"}