Commit | Line | Data |
---|---|---|
126d8fa4 | 1 | # Mouse Tracker for Cubism |
830d0ba4 | 2 | |
126d8fa4 AIL |
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. | |
830d0ba4 AIL |
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 | ||
0acfe9b5 AIL |
17 | Video demo (comparing Mouse Tracker with Facial Landmarks, testing on OBS): |
18 | <https://www.youtube.com/watch?v=MA7H3v9dtxM> | |
830d0ba4 AIL |
19 | |
20 | ## Supporting environments | |
21 | ||
126d8fa4 AIL |
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>`) | |
830d0ba4 AIL |
26 | in the example program, but it should be straightforward to change this |
27 | if you don't have C++17 support. | |
28 | ||
830d0ba4 AIL |
29 | ## Build instructions |
30 | ||
31 | 1. Install dependencies. | |
32 | ||
33 | You will require a recent C/C++ compiler, `make`, `patch`, CMake >= 3.16, | |
cec13e56 | 34 | libxdo, and PulseAudio. To compile the example |
830d0ba4 AIL |
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 | ||
cec13e56 | 39 | libxdo-dev libpulse-dev libgl1-mesa-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libglu1-mesa-dev |
830d0ba4 | 40 | |
cec13e56 | 41 | 2. Clone this repository including its submodule (editline) |
830d0ba4 | 42 | |
cec13e56 | 43 | git clone --recurse-submodules https://github.com/adrianiainlam/mouse-tracker-for-cubism.git |
830d0ba4 | 44 | |
2b1f0c7c AIL |
45 | 3. To build the library only: (Skip this step if you want to build the example |
46 | program. It will be done automatically.) | |
830d0ba4 AIL |
47 | |
48 | cd <path of the git repo> | |
49 | ./build.sh | |
50 | ||
830d0ba4 AIL |
51 | To build the example program: |
52 | ||
126d8fa4 | 53 | 4. Download "Cubism 4 SDK for Native R1" from the Live2D website: |
830d0ba4 AIL |
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 | ||
126d8fa4 | 62 | 5. Go into the |
830d0ba4 AIL |
63 | "example/CubismSdkForNative-4-r.1/Samples/OpenGL/thirdParty/scripts" |
64 | directory and run | |
65 | ||
66 | ./setup_glew_glfw | |
67 | ||
126d8fa4 | 68 | 6. Go back to the "example" directory and run |
830d0ba4 AIL |
69 | |
70 | ./build.sh | |
71 | ||
cec13e56 AIL |
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 | ||
126d8fa4 | 83 | 7. Now try running the example program. From the "example" directory: |
830d0ba4 AIL |
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. | |
126d8fa4 | 106 | * `--config`, `-c`: Path to the configuration file for the Mouse Tracker |
830d0ba4 AIL |
107 | for Cubism library. See below for more details. |
108 | ||
830d0ba4 AIL |
109 | ## Configuration file |
110 | ||
126d8fa4 AIL |
111 | There are fewer tweakable parameters compared to the Facial Landmarks |
112 | library, but I have still kept the configuration file to allow some | |
113 | customization. The file | |
830d0ba4 AIL |
114 | "config.txt" lists and documents all parameters and their default values. |
115 | You can change the values there and pass it to the example program using | |
2b1f0c7c | 116 | the `-c` argument. If using the library directly, the path to this file |
830d0ba4 AIL |
117 | should be passed to the constructor (or pass an empty string to use |
118 | default values). | |
119 | ||
120 | ## License | |
121 | ||
122 | The library itself is provided under the MIT license. By "the library itself" | |
123 | I refer to the following files that I have provided under this repo: | |
124 | ||
126d8fa4 AIL |
125 | * src/mouse_cursor_tracker.cpp |
126 | * include/mouse_cursor_tracker.cpp | |
830d0ba4 | 127 | * and if you decide to build the binary for the library, the resulting |
126d8fa4 | 128 | binary file (typically build/libMouseTrackerForCubism.a) |
830d0ba4 AIL |
129 | |
130 | The license text can be found in LICENSE-MIT.txt, and also at the top of | |
131 | the .cpp and .h files. | |
132 | ||
cec13e56 AIL |
133 | This library depends on "editline" which is included here as a git |
134 | submodule. The fork used here was originally written by Simmule | |
135 | Turner and Rick Salz, made available under the Spencer License 94, | |
136 | now maintained by Joachim Wiberg. See "lib/editline/LICENSE" for more | |
137 | information. | |
138 | ||
139 | (Note: An earlier version of this library linked to GNU Readline as | |
140 | a dependency. I have made a mistake and assumed GNU Readline was LGPL, | |
141 | when in fact it was GPL. This has been corrected within 24 hours, by | |
142 | replacing GNU Readline with editline instead. I apologize to the | |
143 | copyright holders of GNU Readline.) | |
144 | ||
830d0ba4 AIL |
145 | The example program is a patched version of the sample program provided |
146 | by Live2D (because there's really no point in reinventing the wheel), | |
147 | and as such, as per the licensing restrictions by Live2D, is still the | |
148 | property of Live2D. | |
149 | ||
150 | The patch file (example/demo.patch) contains lines showing additions by | |
151 | me, as well as deleted lines and unchanged lines for context. The deleted | |
152 | and unchanged lines are obviously still owned by Live2D. For my additions, | |
153 | where substantial enough for me to claim ownership, I release them under | |
154 | the Do What the Fuck You Want to Public License, version 2. The full license | |
155 | text can be found in LICENSE-WTFPL.txt. | |
156 | ||
157 | All other files not mentioned above that I have provided in this repo | |
158 | (i.e. not downloaded and placed here by you), *excluding* the two license | |
159 | documents and files generated by Git, are also released under the Do What | |
160 | the Fuck You Want to Public License, version 2, whose full license text | |
161 | can be found in LICENSE-WTFPL.txt. | |
162 | ||
163 | In order to use example program, or in any other way use this library | |
164 | with the Live2D® Cubism SDK, you must agree to the license by Live2D Inc. | |
165 | Their licenses can be found here: | |
166 | <https://www.live2d.com/en/download/cubism-sdk/download-native/>. | |
167 | ||
830d0ba4 AIL |
168 | This is not a license requirement, but if you find my library useful, |
169 | I'd love to hear from you! Send me an email at spam(at)adrianiainlam.tk -- | |
170 | replacing "spam" with the name of this repo :). | |
171 | ||
172 | ## Contributions | |
173 | ||
174 | Contributions welcome! This is only a hobby weekend project so I don't | |
126d8fa4 | 175 | really have many environments to test it on. Feel free to submit |
830d0ba4 AIL |
176 | issues or pull requests on GitHub, or send questions or patches to me |
177 | (see my email address above) if you prefer email. Thanks :) | |
178 |