Skip to main content
This guide will help you set up gSubs for local development on your machine.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js (version 12 or higher)
  • npm (comes with Node.js)
  • Git for version control

​
Initial setup

1

Fork and clone the repository

First, fork the gSubs repository to your own GitHub account, then clone it to your local machine:
git clone [email protected]:YOUR_USERNAME/gsubs.git
cd gsubs
Replace YOUR_USERNAME with your GitHub username.
2

Install dependencies

Install all required dependencies using npm:
npm install
This command will:
  • Install all dependencies listed in package.json
  • Run the postinstall script to install Electron app dependencies via electron-builder
The postinstall script automatically runs electron-builder install-app-deps to ensure native dependencies are properly compiled for your platform.
3

Start the development server

Run the app in development mode:
npm start
This command launches Electron and opens the gSubs application window. The app will load with the main window (344x540) and you can start testing features immediately.

​
Project dependencies

Understanding the dependencies will help you work with the codebase:

​
Runtime dependencies

  • electron-store (^1.3.0) - Persistent storage for user preferences (language settings, etc.)
  • electron-updater (^4.0.0) - Automatic update functionality
  • jquery (^3.3.1) - DOM manipulation and AJAX requests
  • opensubtitles-api (^5.1.2) - OpenSubtitles subtitle source integration
  • subdb (0.0.3) - SubDB subtitle source integration

​
Development dependencies

  • electron (~9.1.0) - Desktop application framework
  • electron-builder (^20.5.1) - Packaging and building for distribution

​
Development workflow

​
Running the app

When you run npm start, Electron launches the main process defined in main.js, which:
  1. Creates a frameless, transparent browser window (344x540)
  2. Loads app/view/index.html as the entry point
  3. Enables Node.js integration in the renderer process
  4. Initializes the auto-updater

​
Making changes

After making changes to the code:
  1. Renderer process changes (files in app/renderer/, app/js/, app/css/) - Close and restart the app with npm start
  2. Main process changes (main.js) - You must restart the app for changes to take effect
  3. HTML/CSS changes - Restart the app to see updates
Unlike web development, Electron apps don’t support hot-reload by default. You’ll need to close and restart the app after each change.

​
Opening developer tools

To debug the renderer process, uncomment this line in main.js:51: 
mainWindow.webContents.openDevTools();
This will open Chrome DevTools when the app starts, allowing you to inspect elements, view console logs, and debug JavaScript.

​
Testing features

Once the app is running, you can test the core features:

​
Drag and drop

Drag video files (.m4v, .avi, .mpg, .mp4, .webm, .mkv) into the app window to search for subtitles.

​
Search functionality

Use the search box to find subtitles by movie or series name without having a video file.

​
Language selection

Click the flag icon to change the subtitle language. Supported languages:
  • English (en)
  • Español (es)
  • Français (fr)
  • Italiano (it)
  • Nederlands (nl)
  • Polski (pl)
  • Português (pt)
  • Român (ro)
  • Svenska (sv)
  • Türkçe (tr)

​
Troubleshooting

​
Installation issues

If npm install fails:
  1. Clear npm cache: npm cache clean --force
  2. Delete node_modules folder and package-lock.json
  3. Run npm install again

​
Electron version mismatch

If you encounter native module errors, rebuild them for your Electron version: 
npm run postinstall

​
App won’t start

Check the console output for errors. Common issues:
  • Missing dependencies: Run npm install
  • Port conflicts: Ensure no other Electron apps are running
  • File permissions: Ensure you have read/write access to the project directory

​
Next steps

Building

Learn how to build gSubs for production

Architecture

Understand the codebase structure

Build docs developers (and LLMs) love

Get started for freeTalk to us