Change randomIdleMotion default to true
[mouse-tracker-for-cubism.git] / README.md
CommitLineData
126d8fa4 1# Mouse Tracker for Cubism
830d0ba4 2
126d8fa4
AIL
3A library that tracks mouse cursor location and microphone input and
4converts them into Live2D® Cubism SDK parameters.
5
6This is a spin-off project from [Facial Landmarks for Cubism](https://github.com/adrianiainlam/facial-landmarks-for-cubism).
7The objective is to provide similar functionality, but requiring much
8less CPU load, which can be critical if the processor does not support
9AVX instructions. It also does not require the use of a dataset which
10restricts 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.
13It is not part of the SDK itself, and is not affiliated in any way with Live2D
14Inc. The Live2D® Cubism SDK belongs solely to Live2D Inc. You will need to
15agree to Live2D Inc.'s license agreements to use the Live2D® Cubism SDK.*
16
0acfe9b5
AIL
17Video 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
22This library is designed for Linux (or other *nix systems) with X11 and
23PulseAudio.
24
25I have made use of one C++17 library (`<filesystem>`)
830d0ba4
AIL
26in the example program, but it should be straightforward to change this
27if you don't have C++17 support.
28
830d0ba4
AIL
29## Build instructions
30
311. 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 412. 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
453. 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
51To build the example program:
52
126d8fa4 534. 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 625. 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 686. 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 837. 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
91Most command-line arguments are to control the Cubism side of the program.
92Only one argument (`--config`) is used to specify the configuration file
93for 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
111There are fewer tweakable parameters compared to the Facial Landmarks
112library, but I have still kept the configuration file to allow some
113customization. The file
830d0ba4
AIL
114"config.txt" lists and documents all parameters and their default values.
115You can change the values there and pass it to the example program using
2b1f0c7c 116the `-c` argument. If using the library directly, the path to this file
830d0ba4
AIL
117should be passed to the constructor (or pass an empty string to use
118default values).
119
120## License
121
122The library itself is provided under the MIT license. By "the library itself"
123I 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
130The license text can be found in LICENSE-MIT.txt, and also at the top of
131the .cpp and .h files.
132
cec13e56
AIL
133This library depends on "editline" which is included here as a git
134submodule. The fork used here was originally written by Simmule
135Turner and Rick Salz, made available under the Spencer License 94,
136now maintained by Joachim Wiberg. See "lib/editline/LICENSE" for more
137information.
138
139(Note: An earlier version of this library linked to GNU Readline as
140a dependency. I have made a mistake and assumed GNU Readline was LGPL,
141when in fact it was GPL. This has been corrected within 24 hours, by
142replacing GNU Readline with editline instead. I apologize to the
143copyright holders of GNU Readline.)
144
830d0ba4
AIL
145The example program is a patched version of the sample program provided
146by Live2D (because there's really no point in reinventing the wheel),
147and as such, as per the licensing restrictions by Live2D, is still the
148property of Live2D.
149
150The patch file (example/demo.patch) contains lines showing additions by
151me, as well as deleted lines and unchanged lines for context. The deleted
152and unchanged lines are obviously still owned by Live2D. For my additions,
153where substantial enough for me to claim ownership, I release them under
154the Do What the Fuck You Want to Public License, version 2. The full license
155text can be found in LICENSE-WTFPL.txt.
156
157All 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
159documents and files generated by Git, are also released under the Do What
160the Fuck You Want to Public License, version 2, whose full license text
161can be found in LICENSE-WTFPL.txt.
162
163In order to use example program, or in any other way use this library
164with the Live2D® Cubism SDK, you must agree to the license by Live2D Inc.
165Their licenses can be found here:
166<https://www.live2d.com/en/download/cubism-sdk/download-native/>.
167
830d0ba4
AIL
168This is not a license requirement, but if you find my library useful,
169I'd love to hear from you! Send me an email at spam(at)adrianiainlam.tk --
170replacing "spam" with the name of this repo :).
171
172## Contributions
173
174Contributions welcome! This is only a hobby weekend project so I don't
126d8fa4 175really have many environments to test it on. Feel free to submit
830d0ba4
AIL
176issues or pull requests on GitHub, or send questions or patches to me
177(see my email address above) if you prefer email. Thanks :)
178