README.md

   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