1 # Mouse Tracker for Cubism
3 A library that tracks mouse cursor location and microphone input and
4 converts them into Live2D® Cubism SDK parameters.
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.
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.*
17 <!-- TODO maybe make a demo video? -->
19 ## Supporting environments
21 This library is designed for Linux (or other *nix systems) with X11 and
24 I have made use of one C++17 library (`<filesystem>`)
25 in the example program, but it should be straightforward to change this
26 if you don't have C++17 support.
30 1. Install dependencies.
32 You will require a recent C/C++ compiler, `make`, `patch`, CMake >= 3.16,
33 libxdo, and PulseAudio. To compile the example
34 program you will also require the OpenGL library (and its dev headers)
35 among other libraries required for the example program. The libraries I
36 had to install (this list may not be exhaustive) are:
38 libxdo-dev libpulse-dev libgl1-mesa-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libglu1-mesa-dev
40 2. Clone this repository including its submodule (dlib)
42 git clone https://github.com/adrianiainlam/mouse-tracker-for-cubism.git
44 3. To build the library only: (Skip this step if you want to build the example
45 program. It will be done automatically.)
47 cd <path of the git repo>
50 To build the example program:
52 4. Download "Cubism 4 SDK for Native R1" from the Live2D website:
53 <https://www.live2d.com/en/download/cubism-sdk/download-native/>.
55 Extract the archive -- put the "CubismSdkForNative-4-r.1" folder under
56 the "example" folder of this repo.
58 Note: The Cubism SDK is the property of Live2D and is not part of this
59 project. You must agree to Live2D's license agreements to use it.
62 "example/CubismSdkForNative-4-r.1/Samples/OpenGL/thirdParty/scripts"
67 6. Go back to the "example" directory and run
71 7. Now try running the example program. From the "example" directory:
73 cd ./demo_build/build/make_gcc/bin/Demo/
77 ## Command-line arguments for the example program
79 Most command-line arguments are to control the Cubism side of the program.
80 Only one argument (`--config`) is used to specify the configuration file
81 for the Facial Landmarks for Cubism library.
83 * `--window-width`, `-W`: Specify the window width
84 * `--window-height`, `-H`: Specify the window height
85 * `--window-title`, `-t`: Specify the window title
86 * `--root-dir`, `-d`: The directory at which the "Resources" folder will
87 be found. This is where the model data will be located.
88 * `--scale-factor`, `-f`: How the model should be scaled
89 * `--translate-x`, `-x`: Horizontal translation of the model within the
91 * `--translate-y`, `-y`: Vertical translation of the model within the window
92 * `--model`, `-m`: Name of the model to be used. This must be located inside
93 the "Resources" folder.
94 * `--config`, `-c`: Path to the configuration file for the Mouse Tracker
95 for Cubism library. See below for more details.
99 There are fewer tweakable parameters compared to the Facial Landmarks
100 library, but I have still kept the configuration file to allow some
101 customization. The file
102 "config.txt" lists and documents all parameters and their default values.
103 You can change the values there and pass it to the example program using
104 the `-c` argument. If using the library directly, the path to this file
105 should be passed to the constructor (or pass an empty string to use
110 The library itself is provided under the MIT license. By "the library itself"
111 I refer to the following files that I have provided under this repo:
113 * src/mouse_cursor_tracker.cpp
114 * include/mouse_cursor_tracker.cpp
115 * and if you decide to build the binary for the library, the resulting
116 binary file (typically build/libMouseTrackerForCubism.a)
118 The license text can be found in LICENSE-MIT.txt, and also at the top of
119 the .cpp and .h files.
121 The example program is a patched version of the sample program provided
122 by Live2D (because there's really no point in reinventing the wheel),
123 and as such, as per the licensing restrictions by Live2D, is still the
126 The patch file (example/demo.patch) contains lines showing additions by
127 me, as well as deleted lines and unchanged lines for context. The deleted
128 and unchanged lines are obviously still owned by Live2D. For my additions,
129 where substantial enough for me to claim ownership, I release them under
130 the Do What the Fuck You Want to Public License, version 2. The full license
131 text can be found in LICENSE-WTFPL.txt.
133 All other files not mentioned above that I have provided in this repo
134 (i.e. not downloaded and placed here by you), *excluding* the two license
135 documents and files generated by Git, are also released under the Do What
136 the Fuck You Want to Public License, version 2, whose full license text
137 can be found in LICENSE-WTFPL.txt.
139 In order to use example program, or in any other way use this library
140 with the Live2D® Cubism SDK, you must agree to the license by Live2D Inc.
141 Their licenses can be found here:
142 <https://www.live2d.com/en/download/cubism-sdk/download-native/>.
144 This is not a license requirement, but if you find my library useful,
145 I'd love to hear from you! Send me an email at spam(at)adrianiainlam.tk --
146 replacing "spam" with the name of this repo :).
150 Contributions welcome! This is only a hobby weekend project so I don't
151 really have many environments to test it on. Feel free to submit
152 issues or pull requests on GitHub, or send questions or patches to me
153 (see my email address above) if you prefer email. Thanks :)