MaxLiu22/Motion2MixamoRig: turning a video of a person into an animation on a Mixamo rig

Video, or a single photo, onto a Mixamo rig

Motion2MixamoRig transfers the motion of a person in a video, or the pose in a still photo, onto an Adobe Mixamo-rigged 3D character.

The framing for game developers is specific. Give it a single-person action video, or a still, and a Mixamo character, and it writes preview videos plus a skinned character file, a `.glb`, that you can drop into Blender or Unity. The deliverable is therefore not a video of the animation but an asset, which is the point for anyone building a game or a piece of 3D work.

The output for a still is a static 3D pose rather than a motion. The `--image` flag recovers a static pose from a photo of one person and retargets it the same way a video run does, and the previews are four stills in the same views as the video run, plus a left and right orbit clip called `before_after_360_compare.mp4`. You cannot pass `--video` and `--image` at the same time, which is a sensible constraint since they are two different pipelines that share the second half.

The project is Apache-2.0 licensed and describes itself as experimental. Version 0.1.5 is the command line pipeline, and the repository also includes a Blender 4.2 or newer Extension that runs the same pipeline in an external Python environment, with its own instructions under `blender_extension/`.

There is also an `AGENTS.md` in the repository, and the README tells agents to start with it, along with a `CHANGELOG.md`, a `NOTICE.md` and a documentation directory with the README translated into more than a dozen languages, from Simplified and Traditional Chinese through Japanese, Korean, Arabic and Nepali.

The install has a legacy dependency trap

The installation is a short sequence, and one of the lines exists to work around a problem that is easy to hit.

git clone https://github.com/MaxLiu22/Motion2MixamoRig.git
cd Motion2MixamoRig
python -m venv .venv && source .venv/bin/activate

# Install dependencies and this project. chumpy (a legacy package on the
# dependency chain) imports pip in its setup script, which fails with
# "No module named 'pip'" under pip's default isolated build. Install it
# first with isolation turned off, then install this project.
pip install --upgrade pip setuptools wheel \
  && pip install "numpy>=1.26" \
  && pip install --no-build-isolation "chumpy==0.70" \
  && pip install -e .

The explanation is in the comment and it is worth understanding rather than copying. `chumpy`, a legacy package on the dependency chain, imports pip in its setup script, and under pip's default isolated build that import fails because pip is not present in the isolated environment. Installing it with `--no-build-isolation` puts pip back in scope for that step.

The fix is pinned to `chumpy==0.70` and the numpy floor is `>=1.26`, and both pins are the kind of thing that tells you the project is tracking a specific historical dependency graph rather than floating.

The project metadata matches the README. The package is `motion2mixamorig` at version 0.1.5, it requires Python 3.11 or newer, the dependencies are numpy, opencv-python, einops and `gvhmr[preproc,rtmpose]>=1.6`, with the extras named in a comment that explains them, `preproc` for person detection and tracking and `rtmpose` for the ungated 2D pose backend the pipeline uses. The console script is `m2mr`, pointing at `motion2mixamorig.cli:main`.

Five gigabytes of weights and a silent video without ffmpeg

Two things about the runtime are stated up front, and both are the kind of detail that saves an afternoon.

The first is the weight download. Inference weights, GVHMR and so on, are not downloaded during installation. The first `m2mr run` pulls them into `weights/`, about 5 GB, once only.

The second is ffmpeg, which is recommended, with the install commands for macOS and Ubuntu given. The pipeline runs without it, but the output videos will be silent and will not play in a browser.

That second note is easy to skim and expensive to discover later. A video that will not play in a browser is not a cosmetic problem, since the previews are how you check whether the retargeting worked, and a silent preview tells you nothing about timing.

The timings are documented as precisely as the downloads. On a CPU, a thirty second clip takes about eight to fifteen minutes to extract, and later runs of similar length, with the weights already present, take about three to five minutes. Retargeting and rendering are usually a minute or two.

So the cost model is clear before you start. The first run is dominated by a five gigabyte download. The second is dominated by CPU time for the extraction. And everything after that is fast, which is the point of the next section.

The assets you have to fetch, and the filename that catches everyone

The repository does not ship the inputs, and the README is explicit that you have to fetch them. A run needs SMPL-X, a Mixamo character, and either a video or a still.

The SMPL-X body model goes at `assets/body_models/smplx/SMPLX_NEUTRAL.npz`, and the filename must match the table exactly, which is because it is a licensed research model you register for and download rather than something the project can redistribute.

The Mixamo character FBX goes at `assets/mixamo/Y_Bot.fbx`, and you download it with an Adobe account from Mixamo. The FBX, video and image names can be anything, with the exception of the default rig.

That exception is the detail the README singles out. Mixamo's download is named `Y Bot.fbx` with a space, one character off from `Y_Bot.fbx` with an underscore in the table. Rename it to the underscore form and it becomes the default rig, so `m2mr run` without `--rig` uses it. Leaving the space is fine too, because if `Y_Bot.fbx` is missing, the first `.fbx` in `assets/mixamo/` is used.

For the media, the action video goes at `assets/video/<your_clip>.mp4` and the optional pose still at `assets/image/<your_photo>.jpg`, and the requirement on both is the same and strict. A clip with exactly one clearly visible person, head to toe in frame the whole time, with nothing cropped at the edges.

The `assets/video/` folder can hold several videos. Without `--video` or `--image`, the run uses the file most recently added to `assets/video/`, and if that folder is empty it falls back to the latest still in `assets/image/`. That default is convenient and slightly dangerous, since adding a file to test something quietly changes what the next run will pick up.

One person, head to toe, or the run stops

The pipeline enforces the input requirement rather than hoping for it. The README says that each clip or photo must show only one person, head to toe in frame, and that `m2mr doctor` and `m2mr run` stop before extraction if two people are in view.

That is a good design decision for a tool that consumes video, because the failure it prevents is a silent one. A pose estimator given two people produces a blended, meaningless skeleton, and the retargeting step would then faithfully apply that nonsense to the character, and you would spend an hour looking at a rig that is animating perfectly and is simply the wrong person.

Stopping before extraction turns that into an error message, which is the difference between a diagnosis and a mystery.

The `doctor` command is the same idea as a preflight check. The quick start runs it first, and the README says that anything missing is printed with where to download it and where to put it. So a first run on a fresh machine produces a list of what to fetch rather than a stack trace from the middle of a weight download.

The commands themselves are short. `m2mr doctor` checks the environment, `m2mr run` performs a run with no flags, which uses the latest file in `assets/video/` and the default `assets/mixamo/Y_Bot.fbx`, and results land in `outputs/<run-time>_<source>/`, with video runs writing into `videos/` and still runs into `images/`.

The skeleton cache is the feature that makes iteration bearable

The workflow advice in the README is short and it is about avoiding the slow step.

To try a different character, download another one from Mixamo into `assets/mixamo/` and do not rerun with only `--rig`, because that repeats the slow extraction. Pass `--skeleton` to reuse the skeleton from a previous run:

m2mr run --skeleton outputs/<previous-run-dir>/skeleton_motion.npz --rig assets/mixamo/Vampire.fbx

And the document says plainly what that buys. Minutes become tens of seconds.

The separation is the right abstraction. The expensive stage turns pixels into a 3D human skeleton, and that result is independent of which character will wear it. The retargeting and rendering stages are comparatively cheap and depend entirely on the rig. So a user who wants to see the same performance on three characters should extract once and retarget three times, and the tool supports exactly that, with the skeleton written out as an `.npz` file that can be passed back in.

The other flags are `--video` to pick a clip, which combines freely with `--rig`, and `--image` for the still pose route, which produces four preview stills and the 360 degree comparison clip.

Where this is the wrong tool

The first wrong case is footage with more than one person, which the tool refuses rather than approximates. Multi person motion capture is a different problem with a different literature, and a tool that silently averaged two skeletons would be worse than one that stops.

The second is a background job that has to finish promptly. The timings are for a CPU, and eight to fifteen minutes for a thirty second clip on the first extraction, plus a five gigabyte download, is a poor fit for a pipeline with a deadline. The retargeting and rendering stages are quick, but the extraction is the expensive part and it is the part that cannot be skipped unless you already have a skeleton.

The third is a project that cannot accept the licence terms of the inputs. The SMPL-X body model is a research model you register for, and the Mixamo characters come from Adobe under an account, and the project's own Apache licence covers the code, not the assets it needs you to bring. A commercial pipeline has to clear both of those.

The fourth is a production pipeline rather than a prototype. The project says it is experimental, at version 0.1.5, and the artefacts it produces are preview videos and a `.glb` for you to inspect, not a character with a cleaned-up animation curve, a root motion setup or a retargeted clip for a specific engine. The heavy lifting of making that usable is still in your hands.

That said, for the case it does cover, the tooling is unusually complete for an experimental project. There is a doctor command, a documented asset layout, a doctor style preflight, a cache flag that makes iteration fast, a Blender extension that runs the same pipeline in an external Python environment, a changelog, a notice file and a translated documentation set.

Editorial conclusion

Adopt Motion2MixamoRig if you need animation for a Mixamo rigged character and you have a clip or a photo of one person to work from, since the pipeline handles the extraction, the retargeting and the export, and the `--skeleton` flag makes iterating on characters fast. Do not adopt it for multi person footage, since the run stops before extraction when two people are in view, and do not adopt it for a pipeline that has to finish in minutes, since the first run downloads about five gigabytes of weights and a thirty second clip takes eight to fifteen minutes to extract on a CPU. Verify first that you can register for the SMPL-X body model and download a Mixamo character under an Adobe account, that ffmpeg is installed so the preview videos have sound, and that the legacy `chumpy` install step succeeds on your Python 3.11 or newer.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. MaxLiu22/Motion2MixamoRig on GitHub
4. README