Merge pull request #52 from georgeistes/custom-model

Customize Live2D model, Hugging Face support

Author: supreme-gg-gg

README.md

@@ -52,12 +52,35 @@ Some background features can be configured in the sidebar, refer to the [Setup a
 
 You must provide your own ElevenLabs API key for text-to-speech and speech-to-textn features. It can be obtained for free with quite generous usage limits by signing up for an account at [their website](https://elevenlabs.io/).
 
-> [!CAUTION]
-> In the pre-release version, we used to support both ElevenLabs and HuggingFace. However, we have currently discontinued support for HuggingFace since the Kokoro TTS API is not reliable.
+You can also choose to use Hugging Face's Kokoro and Whisper models for TTS and STT. You can obtained a free API key by signing up for an account at [their website](https://huggingface.co/). **However, we recommend using ElevenLabs since the free tier is much more generous for API usage.**
 
 > [!NOTE]
 > In future releases, we might consider adding local TTS and STT models to avoid the need for API keys. However, this will make the extension less accessible to many users who do not have the required hardware since these models are quite large.
 
+### Electron.js
+
+We require `electron.js` to create an overlay window for the cheerleader (because it is dangerous and impossible to do so within the VSCode workspace editor). We recommend installing it globally so you don't need to install it individually for every workspace.
+
+```sh
+npm install -g electron
+```
+
+> [!NOTE]
+> If you do not have electron installed, a terminal will pop up when you launch the cheerleader to prompt you to install it (type Enter or "y" to install).
+
+### Customizing Cheerleader
+
+Other than the existing anime characters, you can use your own Live2D model, either found online or created by yourself with Live2D Cubism. To do this, paste in either the **URL** or **absolute local path** to the `model.json` file in the sidebar settings.
+
+Here are few free collections of Live2D models on GitHub (we do not own nor are affiliated with any of these repositories):
+
+- [iCharlesZ/vscode-live2d-models](https://github.com/iCharlesZ/vscode-live2d-models/tree/master)
+
+- [imuncle/live2d](https://github.com/imuncle/live2d)
+
+> [!CAUTION]
+> Advanced animations and interactions are only supported on the default models we provided, because custom models might not have the same motions defined.
+
 ### Settings
 
 You can configure the following settings in the sidebar (with cheerleader icon) OR the original settings panel (Ctrl+Shift+P -> Preferences: Open Settings (UI)):
@@ -80,9 +103,6 @@ Available setitngs include:
 
 - **Feature Settings**: Configure settings like break reminder interval, time to quit session, etc from both the sidebar and the original settings panel
 
-> [!NOTE]
-> In a future release soon you will be able to bring any Live2D model you want by providing a URL. We will also expand the default catalog to include characters other than anime.
-
 ## Installation
 
 ### VSCode Extensions Marketplace
@@ -151,11 +171,11 @@ In the future, we plan to extend more unique functionalities to the cheerleader
 
 **We believe coding should feel less like solitary, mundane work and more like a creative jam session.** That’s why we built the cheerleader — not just as an assistant, but as a vibrant, voice-driven companion that brings energy, motivation, and a bit of fun to your coding flow.
 
-Most coding agents today (like Copilot, Cursor, or Roo) are powerful but sterile — all utility, no personality. They’re optimized for efficiency, but forget that creativity thrives in an environment that’s playful, human, and a little unexpected. We’re flipping the script by making human-computer interaction not only smart, but emotionally engaging.
+Most coding agents today (like Copilot, Cursor, or Roo) are powerful but sterile — all utility, no personality. They’re optimized for efficiency, but forget that creativity thrives in an environment that’s playful, human, and a little unexpected.
 
-We also see coding as inherently social — even when you’re solo. Whether you’re rubber-ducking a bug or celebrating a passing test, the cheerleader is there to respond, react, and cheer you on in real time.
+We also see coding as inherently social — even when you’re solo. That's why rubber-duck debugging and pair programming have been so popular and effective.
 
-Importantly, we’re not trying to replace mature agentic tools which are optimized and excellent. Cheerleader is here to complement and emphasize **reflection and growth**. It’s ideal for moments when you want to think through a problem, like grinding LeetCode or learning a new language — not just vibe code your way through it. Our goal isn’t to automate away the effort, but to make the effort more meaningful. That’s how human skill is perfected.
+Cheerleader is here to complement these tools and emphasize **reflection and growth**. It’s ideal for moments when you want to think through a problem, like grinding LeetCode or learning a new language — not just vibe code your way through it. Our goal isn’t to automate away the effort, but to make the effort more meaningful. That’s how human skill is perfected.
 
 **We're building a collaborator with charm.** One that talks, listens, celebrates small wins, and nudges you forward when you hit a wall. Programming should be powerful _and_ delightful. That’s our philosophy.
 

live2d-container/index.js

@@ -74,10 +74,21 @@ function showSpeechBubble(text, duration = 3000) {
   }, duration);
 }
 
-const loadModel = async (url) => {
-  model = await live2d.Live2DModel.from(
-    url,
-  );
+const loadModel = async (modelUrl, isCustom = false) => {
+  if (!modelUrl) {
+    console.error('Model URL is not provided');
+    return;
+  }
+  try {
+    console.log('Loading model from URL:', modelUrl);
+    model = await live2d.Live2DModel.from(modelUrl);
+    if (!model) {
+      throw new Error('Failed to create Live2DModel');
+    }
+  } catch (error) {
+    console.error('Error loading model:', error);
+    throw error;
+  }
 
   app.stage.addChild(model);
 
@@ -159,22 +170,26 @@ const loadModel = async (url) => {
     icon: createSVGElement(Icons.CLOSE),
     tooltip: 'Quit Cheerleader'
   });
-  
-  buttonManager.addButton({
-    onClick: () => {
-      model.handleExecuteMotion('vodka', MotionPriority.FORCE);
-    },
-    icon: createSVGElement(Icons.VODKA),
-    tooltip: 'Пить водку'
-  });
 
-  buttonManager.addButton({
-    onClick: () => {
-      model.handleExecuteMotion('CENTER_HoldPhone', MotionPriority.FORCE);
-    },
-    icon: createSVGElement(Icons.PHONE),
-    tooltip: 'Consume brainrot'
-  });
+  // these custom animatinos are only available on the base models
+  // because not all motions are defined for your custom ones
+  if (!isCustom) {
+    buttonManager.addButton({
+      onClick: () => {
+        model.handleExecuteMotion('vodka', MotionPriority.FORCE);
+      },
+      icon: createSVGElement(Icons.VODKA),
+      tooltip: 'Пить водку'
+    });
+
+    buttonManager.addButton({
+      onClick: () => {
+        model.handleExecuteMotion('CENTER_HoldPhone', MotionPriority.FORCE);
+      },
+      icon: createSVGElement(Icons.PHONE),
+      tooltip: 'Consume brainrot'
+    });
+  }
 
   // buttonManager.addButton({
   //   onClick: () => {
@@ -320,17 +335,43 @@ function makeDraggable(model) {
   });
 }
 
-async function changeModel(index) {
-  if (model) {
-    await model.motion("JUMP_BACK", undefined, MotionPriority.FORCE);
-    await new Promise(resolve => {
-      model.internalModel.motionManager.on('motionFinish', resolve);
-    });
-    app.stage.removeChild(model);
-    model = null;
+async function changeModel(data) {
+  console.log('Changing model with data:', data);
+  
+  if (!data) {
+    console.error('No data provided for model change');
+    return;
+  }
+
+  try {
+    // Clean up existing model
+    if (model) {
+      console.log('Cleaning up existing model');
+      await model.motion("JUMP_BACK", undefined, MotionPriority.FORCE);
+      await new Promise(resolve => {
+        model.internalModel.motionManager.on('motionFinish', resolve);
+      });
+      app.stage.removeChild(model);
+      model = null;
+    }
+
+    console.log("Received model data:", data);
+
+    // Determine which model to load
+    if (data.customModelURL) {
+      console.log('Using custom model URL:', data.customModelURL);
+      await loadModel(data.customModelURL, true);
+    } else if (typeof data.modelIndex === 'number' && data.modelIndex >= 0 && data.modelIndex < modelUrls.length) {
+      console.log('Using built-in model index:', data.modelIndex);
+      await loadModel(modelUrls[data.modelIndex]);
+    } else {
+      console.warn('Invalid model data, falling back to first model');
+      await loadModel(modelUrls[0]);
+    }
+    console.log('Model loaded successfully');
+  } catch (error) {
+    console.error('Failed to change model:', error);
   }
-  modelIndex = index;
-  await loadModel(modelUrls[modelIndex]);
 }
 
 window.electronAPI.onStartSpeak((event, message) => {  
@@ -348,7 +389,10 @@ window.electronAPI.onStopSpeak((event, message) => {
 });
 
 window.electronAPI.onChangeModel((event, message) => {
-  changeModel(message.modelIndex);
+  changeModel({
+    modelIndex: message.modelIndex,
+    customModelURL: message.customModelURL
+  });
 });
 
 window.electronAPI.onQuit((event, message) => {  
@@ -370,3 +414,4 @@ window.electronAPI.onQuit((event, message) => {
   });
   await loadModel(modelUrls[modelIndex]);
 })();
+

live2d-container/main.js

@@ -54,7 +54,7 @@ function createWindow() {
     transparent: true,
     frame: false,
     alwaysOnTop: true,
-    focusable: false,
+    focusable: true, // Allow window to be focused for DevTools
     webPreferences: {
       nodeIntegration: true,
       contextIsolation: true,
@@ -68,8 +68,6 @@ function createWindow() {
 
   // Welcome message in terminal (because the terminal cannot be closed, show something interesting)
   showWelcomeMessage();
-  // open devtools for debugging
-  // mainWindow.webContents.openDevTools();
 
   if (USE_WEBSOCKET) {
     // Connect to VSCode extension's WebSocket server
@@ -87,7 +85,7 @@ function createWindow() {
         stopSpeak();
       }
       if (data.type === 'changeModel') {
-        changeModel(data.modelIndex);
+        changeModel(data);
       }
       // if (data.type === 'window-info') {
       //   const { x, y, width, height } = data.data;
@@ -101,12 +99,29 @@ function createWindow() {
   }
 }
 
-app.whenReady().then(() => {
-  createWindow();
-});
+// Check for single instance lock
+const gotTheLock = app.requestSingleInstanceLock();
+
+if (!gotTheLock) {
+  app.quit();
+} else {
+  app.on('second-instance', (event, commandLine, workingDirectory) => {
+    // A second instance tried to run - focus our window
+    if (mainWindow) {
+      if (mainWindow.isMinimized()) mainWindow.restore();
+      mainWindow.focus();
+    }
+  });
+
+  app.whenReady().then(() => {
+    createWindow();
+  });
+}
 
 app.on('window-all-closed', () => {
-  quitApp();
+  if (process.platform !== 'darwin') {
+    quitApp();
+  }
 });
 
 ipcMain.on('onCloseButton', () => {
@@ -148,18 +163,30 @@ function stopSpeak() {
   mainWindow.webContents.send('stopSpeak');
 }
 
-function changeModel(modelIndex) {
+function changeModel(data) {
   if (!mainWindow) return;
-  mainWindow.webContents.send('changeModel', { modelIndex });
+  mainWindow.webContents.send('changeModel', {
+    modelIndex: data.modelIndex,
+    customModelURL: data.customModelURL
+  });
 }
 
 function quitApp(mode = "graceful") {
   if (mode === "force") {
-    app.quit();
+    cleanupAndQuit();
     return;
   }
-  mainWindow.webContents.send('quit', {});
-  setTimeout(() => {
-    app.quit();
-  }, 4000); // wait for 4 seconds to let the animation finish
+  if (mainWindow) {
+    mainWindow.webContents.send('quit', {});
+    setTimeout(cleanupAndQuit, 4000); // wait for 4 seconds to let the animation finish
+  } else {
+    cleanupAndQuit();
+  }
+}
+
+function cleanupAndQuit() {
+  if (ws) {
+    ws.close();
+  }
+  app.quit();
 }

package-lock.json

@@ -3,14 +3,14 @@
   "displayName": "Cheerleader",
   "publisher": "cheerleader",
   "description": "Supercharge your dev experience with an anime coding companion",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "engines": {
     "vscode": "^1.99.0"
   },
   "icon": "assets/cheerleader_icon.png",
   "author": {
     "name": "James Zheng and Jet Chiang",
-    "email": "endernoke@gmail.com"
+    "email": "jetjiang.ez@gmail.com"
   },
   "pricing": "Free",
   "categories": [
@@ -27,7 +27,7 @@
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/endernoke/vscode-cheerleader/issues",
-    "email": "endernoke@gmail.com"
+    "email": "jetjiang.ez@gmail.com"
   },
   "homepage": "https://github.com/endernoke/vscode-cheerleader/blob/main/README.md",
   "activationEvents": [
@@ -191,6 +191,11 @@
           "default": "gpt-4o",
           "description": "The Copilot model family to use"
         },
+        "cheerleader.model.customModelURL": {
+          "type": "string",
+          "default": "",
+          "description": "The URL of a custom Live2D model (locally or online) to use"
+        },
         "cheerleader.audio.provider": {
           "type": "string",
           "enum": [
@@ -260,6 +265,7 @@
     "play-sound": "^1.1.6",
     "tsx": "^4.19.3",
     "uuid": "^11.1.0",
+    "wavefile": "^11.0.0",
     "ws": "^8.18.1"
   }
 }

package.json

@@ -28,7 +28,7 @@ async function monitorRotting() {
     const audioFilePath = vscode.Uri.file(
       `${globalContext.extensionUri.fsPath}/assets/rotting/${fileName}`
     ).fsPath;
-    await playAudioFromFile(audioFilePath, text, 10);
+    await playAudioFromFile(audioFilePath, text, 10 * 1000);
   }
 
   globalContext.globalState.update("lastProductiveState", currentProductiveState);