| 1 | # Mouse Tracker for Cubism |
| 2 | |
| 3 | A library that tracks mouse cursor location and microphone input and |
| 4 | converts them into Live2D® Cubism SDK parameters. |
| 5 | |
| 6 | This is a spin-off project from [Facial Landmarks for Cubism](https://github.com/adrianiainlam/facial-landmarks-for-cubism). |
| 7 | The objective is to provide similar functionality, but requiring much |
| 8 | less CPU load, which can be critical if the processor does not support |
| 9 | AVX instructions. It also does not require the use of a dataset which |
| 10 | restricts commercial use, and it does not require a webcam. |
| 11 | |
| 12 | *Disclaimer: This library is designed for use with the Live2D® Cubism SDK. |
| 13 | It is not part of the SDK itself, and is not affiliated in any way with Live2D |
| 14 | Inc. The Live2D® Cubism SDK belongs solely to Live2D Inc. You will need to |
| 15 | agree to Live2D Inc.'s license agreements to use the Live2D® Cubism SDK.* |
| 16 | |
| 17 | Video demo (comparing Mouse Tracker with Facial Landmarks, testing on OBS): |
| 18 | <https://www.youtube.com/watch?v=MA7H3v9dtxM> |
| 19 | |
| 20 | ## Supporting environments |
| 21 | |
| 22 | This library is designed for Linux (or other *nix systems) with X11 and |
| 23 | PulseAudio. |
| 24 | |
| 25 | I have made use of one C++17 library (`<filesystem>`) |
| 26 | in the example program, but it should be straightforward to change this |
| 27 | if you don't have C++17 support. |
| 28 | |
| 29 | ## Build instructions |
| 30 | |
| 31 | 1. Install dependencies. |
| 32 | |
| 33 | You will require a recent C/C++ compiler, `make`, `patch`, CMake >= 3.16, |
| 34 | libxdo, PulseAudio, and a stable version of gtkmm 3. To compile the example |
| 35 | program you will also require the OpenGL library (and its dev headers) |
| 36 | among other libraries required for the example program. The libraries I |
| 37 | had to install (this list may not be exhaustive) are: |
| 38 | |
| 39 | libxdo-dev libpulse-dev libgl1-mesa-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libglu1-mesa-dev libgtkmm-3.0-dev |
| 40 | |
| 41 | 2. Clone this repository including its submodule (editline) |
| 42 | |
| 43 | git clone --recurse-submodules https://github.com/adrianiainlam/mouse-tracker-for-cubism.git |
| 44 | |
| 45 | 3. To build the library only: (Skip this step if you want to build the example |
| 46 | program. It will be done automatically.) |
| 47 | |
| 48 | cd <path of the git repo> |
| 49 | ./build.sh |
| 50 | |
| 51 | To build the example program: |
| 52 | |
| 53 | 4. Download "Cubism 4 SDK for Native R1" from the Live2D website: |
| 54 | <https://www.live2d.com/en/download/cubism-sdk/download-native/>. |
| 55 | |
| 56 | Extract the archive -- put the "CubismSdkForNative-4-r.1" folder under |
| 57 | the "example" folder of this repo. |
| 58 | |
| 59 | Note: The Cubism SDK is the property of Live2D and is not part of this |
| 60 | project. You must agree to Live2D's license agreements to use it. |
| 61 | |
| 62 | 5. Go into the |
| 63 | "example/CubismSdkForNative-4-r.1/Samples/OpenGL/thirdParty/scripts" |
| 64 | directory and run |
| 65 | |
| 66 | ./setup_glew_glfw |
| 67 | |
| 68 | 6. Go back to the "example" directory and run |
| 69 | |
| 70 | ./build.sh |
| 71 | |
| 72 | Note: I have observed that sometimes, on the first build, a failure |
| 73 | will be reported, such as: |
| 74 | |
| 75 | [ 98%] Completed 'editline' |
| 76 | [ 98%] Built target editline |
| 77 | Makefile:149: recipe for target 'all' failed |
| 78 | make: *** [all] Error 2 |
| 79 | |
| 80 | I have no idea why, but seems like running build.sh again solves the |
| 81 | issue. Please open an issue / contact me if not. |
| 82 | |
| 83 | 7. Now try running the example program. From the "example" directory: |
| 84 | |
| 85 | cd ./demo_build/build/make_gcc/bin/Demo/ |
| 86 | ./Demo |
| 87 | |
| 88 | |
| 89 | ## Command-line arguments for the example program |
| 90 | |
| 91 | Most command-line arguments are to control the Cubism side of the program. |
| 92 | Only one argument (`--config`) is used to specify the configuration file |
| 93 | for the Facial Landmarks for Cubism library. |
| 94 | |
| 95 | * `--window-width`, `-W`: Specify the window width |
| 96 | * `--window-height`, `-H`: Specify the window height |
| 97 | * `--window-title`, `-t`: Specify the window title |
| 98 | * `--root-dir`, `-d`: The directory at which the "Resources" folder will |
| 99 | be found. This is where the model data will be located. |
| 100 | * `--scale-factor`, `-f`: How the model should be scaled |
| 101 | * `--translate-x`, `-x`: Horizontal translation of the model within the |
| 102 | window |
| 103 | * `--translate-y`, `-y`: Vertical translation of the model within the window |
| 104 | * `--model`, `-m`: Name of the model to be used. This must be located inside |
| 105 | the "Resources" folder. |
| 106 | * `--old-param-id`, `-o`: If set to 1, translate new (Cubism 3+) parameter |
| 107 | IDs to old (Cubism 2.1) IDs. This is necessary, for example, for |
| 108 | [the Chitose model available from Live2D](https://www.live2d.com/en/download/sample-data/). |
| 109 | * `--config`, `-c`: Path to the configuration file for the Mouse Tracker |
| 110 | for Cubism library. See below for more details. |
| 111 | |
| 112 | ## Configuration file |
| 113 | |
| 114 | There are fewer tweakable parameters compared to the Facial Landmarks |
| 115 | library, but I have still kept the configuration file to allow some |
| 116 | customization. The file |
| 117 | "config.txt" lists and documents all parameters and their default values. |
| 118 | You can change the values there and pass it to the example program using |
| 119 | the `-c` argument. If using the library directly, the path to this file |
| 120 | should be passed to the constructor (or pass an empty string to use |
| 121 | default values). |
| 122 | |
| 123 | ## License |
| 124 | |
| 125 | The library itself is provided under the MIT license. By "the library itself" |
| 126 | I refer to the following files that I have provided under this repo: |
| 127 | |
| 128 | * src/mouse_cursor_tracker.cpp |
| 129 | * src/mouse_cursor_tracker_gui.cpp |
| 130 | * src/gui.glade |
| 131 | * include/mouse_cursor_tracker.h |
| 132 | * and if you decide to build the binary for the library, the resulting |
| 133 | binary file (typically build/libMouseTrackerForCubism.a) |
| 134 | |
| 135 | The license text can be found in LICENSE-MIT.txt, and also at the top of |
| 136 | the .cpp and .h files. |
| 137 | |
| 138 | This library depends on "editline" which is included here as a git |
| 139 | submodule. The fork used here was originally written by Simmule |
| 140 | Turner and Rick Salz, made available under the Spencer License 94, |
| 141 | now maintained by Joachim Wiberg. See "lib/editline/LICENSE" for more |
| 142 | information. |
| 143 | |
| 144 | (Note: An earlier version of this library linked to GNU Readline as |
| 145 | a dependency. I have made a mistake and assumed GNU Readline was LGPL, |
| 146 | when in fact it was GPL. This has been corrected within 24 hours, by |
| 147 | replacing GNU Readline with editline instead. I apologize to the |
| 148 | copyright holders of GNU Readline.) |
| 149 | |
| 150 | The example program is a patched version of the sample program provided |
| 151 | by Live2D (because there's really no point in reinventing the wheel), |
| 152 | and as such, as per the licensing restrictions by Live2D, is still the |
| 153 | property of Live2D. |
| 154 | |
| 155 | The patch file (example/demo.patch) contains lines showing additions by |
| 156 | me, as well as deleted lines and unchanged lines for context. The deleted |
| 157 | and unchanged lines are obviously still owned by Live2D. For my additions, |
| 158 | where substantial enough for me to claim ownership, I release them under |
| 159 | the Do What the Fuck You Want to Public License, version 2. The full license |
| 160 | text can be found in LICENSE-WTFPL.txt. |
| 161 | |
| 162 | All other files not mentioned above that I have provided in this repo |
| 163 | (i.e. not downloaded and placed here by you), *excluding* the two license |
| 164 | documents and files generated by Git, are also released under the Do What |
| 165 | the Fuck You Want to Public License, version 2, whose full license text |
| 166 | can be found in LICENSE-WTFPL.txt. |
| 167 | |
| 168 | In order to use example program, or in any other way use this library |
| 169 | with the Live2D® Cubism SDK, you must agree to the license by Live2D Inc. |
| 170 | Their licenses can be found here: |
| 171 | <https://www.live2d.com/en/download/cubism-sdk/download-native/>. |
| 172 | |
| 173 | This is not a license requirement, but if you find my library useful, |
| 174 | I'd love to hear from you! Send me an email at spam(at)adrianiainlam.tk -- |
| 175 | replacing "spam" with the name of this repo :). |
| 176 | |
| 177 | ## Contributions |
| 178 | |
| 179 | Contributions welcome! This is only a hobby weekend project so I don't |
| 180 | really have many environments to test it on. Feel free to submit |
| 181 | issues or pull requests on GitHub, or send questions or patches to me |
| 182 | (see my email address above) if you prefer email. Thanks :) |
| 183 | |