{"id":17025974,"url":"https://github.com/scherroman/mugen","last_synced_at":"2026-04-13T00:30:20.713Z","repository":{"id":13169287,"uuid":"73780798","full_name":"scherroman/mugen","owner":"scherroman","description":"A command-line music video generator based on rhythm","archived":false,"fork":false,"pushed_at":"2023-10-04T00:52:40.000Z","size":24453,"stargazers_count":223,"open_issues_count":8,"forks_count":39,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-10-14T07:31:57.319Z","etag":null,"topics":["amv","audio","command-line","librosa","montage","moviepy","mugen","music-video","python","remix","rhythm","tesseract","video"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scherroman.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":"2016-11-15T05:51:36.000Z","updated_at":"2024-10-11T08:35:47.000Z","dependencies_parsed_at":"2024-10-14T07:31:37.039Z","dependency_job_id":"80e3a9a9-79d3-4e0f-9362-e4efc4243498","html_url":"https://github.com/scherroman/mugen","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scherroman%2Fmugen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scherroman%2Fmugen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scherroman%2Fmugen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scherroman%2Fmugen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scherroman","download_url":"https://codeload.github.com/scherroman/mugen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239997218,"owners_count":19731368,"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":["amv","audio","command-line","librosa","montage","moviepy","mugen","music-video","python","remix","rhythm","tesseract","video"],"created_at":"2024-10-14T07:30:17.175Z","updated_at":"2026-04-13T00:30:20.672Z","avatar_url":"https://github.com/scherroman.png","language":"Python","funding_links":["https://ko-fi.com/scherroman"],"categories":["Python"],"sub_categories":[],"readme":"```\n\n _ __ ___  _   _  __ _  ___ _ __\n| '_ ` _ \\| | | |/ _` |/ _ \\ '_ \\\n| | | | | | |_| | (_| |  __/ | | |\n|_| |_| |_|\\__,_|\\__, |\\___|_| |_|\n                  |___/\n```\n\n[![tests](https://img.shields.io/github/actions/workflow/status/scherroman/mugen/test.yml?branch=master\u0026label=tests\u0026logo=github)](https://github.com/scherroman/mugen/actions/workflows/test.yml)\n[![coverage](https://img.shields.io/codecov/c/github/scherroman/mugen?label=coverage\u0026logo=codecov)](https://codecov.io/gh/scherroman/mugen)\n[![Maintainability](https://api.codeclimate.com/v1/badges/76b9fd9b7ca0250ad526/maintainability)](https://codeclimate.com/github/scherroman/mugen/maintainability)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![license](https://img.shields.io/github/license/scherroman/mugen?color=blue)](https://github.com/scherroman/mugen/blob/master/LICENSE)\n[![Ko-Fi](https://img.shields.io/badge/buy%20me%20a%20coffee-F16061?logo=ko-fi\u0026logoColor=white)](https://ko-fi.com/scherroman)\n\nA command-line music video generator based on rhythm\n\nUse it to brainstorm AMVs, montages, and more! [Check it out](https://youtu.be/ZlTR6XULe5M).\n\nBuilt with [moviepy](https://github.com/Zulko/moviepy) programmatic video editing and [librosa](https://github.com/librosa/librosa) audio analysis.\n\n## Strategy\n\n1. Provide an audio file and a set of video files\n\n2. Perform rhythm analysis to identify beat locations\n\n3. Generate a set of random video segments synced to the beat\n\n4. Discard segments with scene changes, detectable text (e.g. credits), or low contrast (i.e. solid colors, very dark scenes)\n\n5. Combine the segments in order, overlay the audio, and output the resulting music video\n\n## Installation\n\nMugen is supported across Linux, macOS, and Windows.\n\n**1. Install [Miniconda](http://conda.pydata.org/miniconda.html)**\n\nMiniconda helps create an isolated virtual environment and install the project's dependencies across platforms.\n\n**2. Download this repository**\n\n```\ngit clone https://github.com/scherroman/mugen\n```\n\n**3. Create the project's virtual environment**\n\n```\nconda env create --file mugen/environment.yml\n```\n\n**4. Activate the virtual environment**\n\n```\nconda activate mugen\n```\n\n## Usage\n\n### Help Menu\n\n---\n\n```\nmugen --help\nmugen create --help\nmugen preview --help\n```\n\nUse the above commands at any time to clarify the examples below and view the full list of available options.\n\nBy default output files are sent to the desktop. This can be changed with the `-od --output-directory` option.\n\n### Preview a music video\n\n---\n\nCreate a quick preview of how your music video will be cut to the music with beeps and flashes.\n\nIt's common for beat timing to be a little off or too fast, so to save time it's recommended to generate and tweak previews beforehand to make sure the timing feels right.\n\n```\nmugen preview --audio-source Spazzkid_Goodbye.mp3\n```\n\n**Slow down cuts to every other beat**\n\n```\n--events-speed 1/2\n```\n\n**Offset the grouping of beats when slowing down cuts**\n\n```\n--events-speed 1/4 --events-speed-offset 2\n```\n\n**Globally offset beat locations in seconds**\n\n```\n--events-offset 0.25\n```\n\n**Slow down cuts for leading and trailing weak beats**\n\n```\n--beats-mode weak_beats --group-events-by-type --group-speeds 1/2 1 1/4\n```\n\n**Control the speed of cuts for specific sections**\n\n```\n--group-events-by-slices (0,23) (23,32) (32,95) (160,225) (289,321) (321,415) --group-speeds 1/2 0 1/4 1/2 1/2 1/4\n```\n\n**Input event locations manually in seconds**\n\n```\n--event-locations 2 4 6 10.5 11 12\n```\n\n**Use onsets instead of beats**\n\n```\n--audio-events-mode onsets\n```\n\n### Create a music video\n\n---\n\n```\nmugen create --audio-source MACINTOSH_PLUS_420.mp3 --video-sources TimeScapes.mkv\n```\n\n**Use a series 60% of the time and a movie 40% of the time**\n\n```\n--video-sources Neon_Genesis_Evangelion/ The_End_of_Evangelion.mkv --video-source-weights .6 .4\n```\n\n**Use all files and subdirectories under a directory**\n\n```\n--video-sources Miyazaki/*\n```\n\n**Use files that match a prefix**\n\n```\n--video-sources Higurashi/S01*\n```\n\n**Allow clips with cuts and repeat clips**\n\n```\n--exclude-video-filters not_has_cut not_is_repeat\n```\n\n**Use only clips that have text**\n\n```\n--video-filters has_text\n```\n\n**Save individual segments**\n\nTo save all the segments that make up the music video as separate files:\n\n```\n--save-segments\n```\n\nTo save all the rejected segments that did not pass filters as separate files:\n\n```\n--save-rejected-segments\n```\n\nThese will be saved as `.mp4` files in folders alongside the music video.\n\n## Python Usage\n\n### Preview a music video\n\n---\n\n```\nfrom mugen import MusicVideoGenerator\n\ngenerator = MusicVideoGenerator(\"Pogo - Forget.mp3\")\nbeats = generator.audio.beats()\nbeats.speed_multiply(1/2)\n\npreview = generator.preview_from_events(beats, \"forget-preview.mkv\")\npreview.write_to_video_file(\"preview.mkv\")\n```\n\n### Create a music video\n\n---\n\n```\nfrom mugen import MusicVideoGenerator\n\ngenerator = MusicVideoGenerator(\"in love with a ghost - flowers.mp3\", [\"wolf children.mkv\"])\nbeats = generator.audio.beats()\nbeat_groups = beats.group_by_slices([(0, 23), (23, 32), (32, 95), (160, 225), (289,331), (331, 415)])\nbeat_groups.selected_groups.speed_multiply([1/2, 0, 1/4, 1/2, 1/2, 1/4])\nbeats = beat_groups.flatten()\n\nmusic_video = generator.generate_from_events(beats)\nmusic_video.write_to_video_file(\"flowers.mkv\")\nmusic_video.save(\"flowers.pickle\")\n```\n\n### Replace a segment in a music video\n\n---\n\n```\nfrom mugen import VideoSource, SourceSampler, MusicVideo\n\nmusic_video = MusicVideo.load(\"flowers.pickle\")\nwolf_children = VideoSource(\"wolf children.mkv\", weight=.2)\nspirited_away = VideoSource(\"spirited away.mkv\", weight=.8)\nsampler = SourceSampler([wolf_children, spirited_away])\nmusic_video.segments[1] = sampler.sample(music_video.segments[1].duration)\n\nmusic_video.write_to_video_file(\"flowers.mkv\")\n```\n\n### Preview a segment in a music video\n\n---\n\n```\nfrom mugen import MusicVideo\n\nmusic_video = MusicVideo.load(\"flowers.pickle\")\n\n''' Basic Previews (less smooth) '''\n\n# Use a lower fps to reduce lag in playback\nmusic_video.segments[1].preview(fps=10)\n\n# Preview a frame at a specific time (seconds)\nmusic_video.segments[1].show(.5)\n\n''' Jupyter Notebook Previews (smoother) '''\n\nmusic_video.segments[1].ipython_display(autoplay=1, loop=1, width=400)\n\n# Preview a frame at a specific time (seconds)\nmusic_video.segments[1].ipython_display(t=.5, width=400)\n```\n\n## Notes\n\n### Subtitles\n\nThe videos generated by `create` and `preview` include a subtitle track which display segment types, numbers, and locations.\n\n### Text detection\n\nCurrently text detection uses the [Tesseract](https://github.com/tesseract-ocr/tesseract) optical character recognition engine and thus has been trained mainly on documents with standard type fonts. Credit sequences with nonstandard or skewed fonts will likely not be detected. It is also possible for Tesseract to occasionally falsely detect text in some images.\n\n## Troubleshooting\n\n### Progress is stuck\n\nThe most common reason progress gets stuck is that mugen is trying but can't find any more segments from your video source(s) that pass the default video filters listed under `mugen create --help`. The `not_is_repeat` and `not_has_cut` filters in particular could be causing this if your video source is especially short and/or with little to no time between scene changes. The first one throws out segments that have already been used, and the latter throws out segments where there are scene changes detected. Try using one or more videos that are longer than your music, or otherwise disable the filters with `--exclude-video-filters not_has_cut not_is_repeat`.\n\n## Contributing\n\nThanks for considering contributing! To get started, see the [contributing documentation](documentation/CONTRIBUTING.md) for details on development setup and submitting pull requests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscherroman%2Fmugen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscherroman%2Fmugen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscherroman%2Fmugen/lists"}