Open-source project
xianfei/SysMocap avatar
xianfei/SysMocap

SysMocap: an empty architecture section, two licenses, and a Gatekeeper switch

A real-time motion capture system for 3D virtual character animating.

3,260 stars492 forksJavaScriptMPL-2.0

At a glance

What is it?
SysMocap turns a camera into skeleton motion for a 3D avatar through MediaPipe Holistic and kalidokit, packaged as Windows archives and macOS disk images with Linux left as source only. Its documentation and its build file disagree with each other in several places.
Who is it for?
Read SysMocap as a desktop app with a build pipeline attached, and it fits you if you already have a VRM or Mixamo model and want mocap without wiring a browser tab yourself. Before the first launch on macOS, know that the documented route disables Gatekeeper for the whole machine and strips the quarantine attribute from the app, and decide which of the two license statements you are following before you redistribute anything you build.
Can I use it commercially?
Yes, with conditions. MPL-2.0 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
Is it still maintained?
Yes. The repository last received commits 158 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • xianfei/SysMocap3,260 ★ · +40
Star history
Repository2026-09-242026-11-15
xianfei/SysMocap3.2k3.3k

40 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The system architecture heading has nothing under it

The README carries a level-three heading reading `System architecture`, and the very next line is another level-three heading, `How to Download prebuilt package (Windows & macOS)`. No diagram, no paragraph and no link sits between them. The pieces a reader would need to rebuild that picture are named in other places instead: `main.js` is the entry point in `package.json`, `webserv` appears in the dependency note as part of the un-bundled runtime, and `src/`, `utils/`, `models/` and `vite.config.mjs` sit at the root. None of it is assembled into a description, and no part of the README points into the `docs/` directory standing beside them. The one place the pipeline does get explained is the closing citation, an ISM AR-Adjunct 2022 paper on expressive avatar animation from monocular video whose second author is this repository's owner, with its volume and number fields left empty.

The macOS install asks you to switch off Gatekeeper

The macOS download section gives two instructions after the disk images. The first says you need to set Gatekeeper to Anywhere in System Settings, using `sudo spctl --master-disable`. That is not a per-app permission; it turns the check off for the whole machine. The second tells you to clear the quarantine attribute from the installed application when macOS reports it as damaged, with `sudo xattr -r -d com.apple.quarantine /Applications/SysMocap.app`. The build side matches that advice and adds nothing to it: the disk image tasks run `builddmgjsonx86.js` or `builddmgjsonarm.js`, print the `dmgcfg.json` they generated, and hand it to a globally installed `appdmg`, with no signing or notarization step among the thirteen scripts, although `entitlements.mac.plist` is checked in at the root. Nothing explains why the images arrive unsigned.

One package.json writes the version variable two ways

The version variable shows up in four packaging tasks and not in one form. The two Windows archive tasks interpolate it as `%npm_package_version%`, the Windows shell form, while both disk image tasks use `$npm_package_version`, the POSIX form. Each convention matches the shell its own task targets, so the file works on both platforms and reads as though it were written twice. The disk image tasks also chain shell syntax inside npm, calling `cat` on the config they just produced and deleting it at the end, and they need `appdmg` installed globally first, which is what the `dmgtool` task does. Two further names do not line up with their output: `msix64` and `msixarm` call `buildmsi.js`, and the artifacts the download section asks you to pick from all end in `.msi`.

npm start rebuilds the entire app before Electron opens

Running from source is four commands:

shell
git clone https://github.com/xianfei/SysMocap.git
cd SysMocap
npm i
npm start

`start` is `npm run build && electron .` and `build` is `vite build`, so the first launch pays for a full production bundle before any window appears. The thirteen scripts hold no watch task, no test task and no lint task. The install command is `npm i` even though `package-lock.json` is committed at the root, and the README asks for the latest Node.js without naming a version. On versioning, `package.json` reads `0.8.0`, the newest tag is `v0.8.0` from 2026-06-10, the tag before it `v0.7.3` from 2025-03-25 and the one before that `v0.7.2` from 2024-07-18, while the last commit on `main` carries that same June date, minutes ahead of the tag being published.

One port for HTTP and HTTPS, with node_modules served beside it

The notice section is a single sentence: HTTP and HTTPS use the same port in mocap data forwarding. WebXR support on that forwarding path is marked HTTPS only, which is where the distinction earns its place for a headset browser. The sentence does not say what listens, on which interface, or whether a credential is asked for. A dependency note inside `package.json` widens the picture: runtime packages stay in `dependencies` because the un-bundled `main.js` and `webserv` require them, or because they are served from `/node_modules` to the web client, naming `three`, `@pixiv/three-vrm`, `kalidokit` and `socket.io`. Build-only packages are moved into `dist/node_modules` by `vite-plugin-static-copy` for the packager to prune. So the process that accepts motion data also serves package files over HTTP, and anyone placing this on a shared network has to look at that listener themselves.

Automatic skeleton detection covers two formats, the rest is manual

Prebuilt packages exist for Windows as a portable archive and an installer in both x64 and arm64 flavors, and for macOS as disk images for Intel and M-series chips; Linux is marked source code only. Once a model is loaded, twelve named nodes are required in a glTF, glb or FBX file: Hips, Neck, Chest, Spine, four arm segments and four leg segments. Automatic detection is claimed for VRM 0.x, VRM 1.0 and Mixamo FBX, and any other skeleton structure is bound by hand, as the note beside the list says. Hips is the only node taking both position and rotation, described in the text as `Rratation only for other nodes`, misspelling included. The ordering is inconsistent too, with the right arm ahead of the left and the left leg ahead of the right.

The translation guide points at a directory the root does not have

To contribute a language the README says to add a translation in `utils/language.js` and then modify `mainview/framework.html`, followed by an HTML snippet showing a settings row. The repository root has `utils/`, and it has no `mainview/`. The snippet mixes frameworks as well: it uses `mdui-select`, `mdui-icon` and `material-icons` class names with mustache-style `{{language.tabSettings.ui.language}}` interpolation, while the credits name Electron and Vue.js as the GUI framework. The switch it shows carries two values, one for Simplified Chinese and one for English, which lines up with the `README.zh-cn.md` linked from the header. That header is where the upkeep shows as well: two of its badge links point at `#` with nothing inside them, and the star history entry has no image text and a URL ending in `&Date` with no value.

Two license statements and a LICENSE file beside them

The repository's license field reads MPL-2.0. `package.json` declares `"license": "ISC"`, and a `LICENSE` file sits at the root. Those are different grants, and the difference matters the moment anyone ships a build or folds the app into something else, because MPL-2.0 carries source obligations for modified files while ISC is a short permissive notice. Nothing in the repository says which one governs, and the four packaging tasks give no hint either. The third-party code it names sits alongside that ambiguity: MediaPipe for the capture step, kalidokit, credited as `Calulate Mocap Data`, for computing the motion data, Electron and Vue.js for the interface, and Material color utilities for color picking. All four are linked, and none is vendored into the tree.

Editorial conclusion

Read SysMocap as a desktop app with a build pipeline attached, and it fits you if you already have a VRM or Mixamo model and want mocap without wiring a browser tab yourself. Before the first launch on macOS, know that the documented route disables Gatekeeper for the whole machine and strips the quarantine attribute from the app, and decide which of the two license statements you are following before you redistribute anything you build. Do not expect a Linux package, phone capture or a written system architecture; none of the three is here. Two things deserve a look before you commit: the forwarding port, which serves HTTP and HTTPS on the same one and hands `/node_modules` to the web client, and the install step, which runs `npm i` against a committed lock file and pays for a production build on every start.

Frequently asked questions

How does SysMocap turn a camera into skeleton motion?

MediaPipe Holistic does the capture step and kalidokit computes the motion data, after which the result is bound to a model's skeleton. Automatic detection covers VRM 0.x, VRM 1.0 and Mixamo FBX files; any other structure is mapped by hand against twelve named nodes, with Hips the only one taking both position and rotation.

Is SysMocap free to use?

Nothing in the repository is sold: the prebuilt packages come from the GitHub releases page as a Windows portable archive, a Windows installer and macOS disk images. Two license statements disagree about what the code is, though, since the repository's license field reads MPL-2.0 while `package.json` declares ISC, and a `LICENSE` file sits at the root.

Can SysMocap do motion capture on a phone?

This repository does not cover phones. It ships a Windows portable archive and installer for x64 and arm64, macOS disk images for Intel and M-series chips, and Linux as source code only, and its run-from-source path asks for the latest Node.js on a desktop.

What does a SysMocap setup involve?

A camera, a model with the twelve required skeleton nodes, and one of the desktop builds, or Node.js for the source path where `npm start` runs a production build before Electron launches. The forwarding port serves HTTP and HTTPS on the same one and serves `/node_modules` to the web client, so it belongs on a network you control.

Official sources

  1. Issues
  2. License: MPL-2.0
  3. README
  4. Releases
  5. xianfei/SysMocap on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/xianfei-sysmocap.svg)](https://hysenlabs.com/projects/xianfei-sysmocap)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/xianfei-sysmocap.svg)](https://hysenlabs.com/projects/xianfei-sysmocap)

Was this useful?