Skip to main content
This guide will walk you through downloading your first subtitle using gSubs. You’ll learn the drag-and-drop workflow that makes subtitle hunting effortless.
Before starting, make sure you have installed gSubs on your system.

​
Your first subtitle download

1

Launch gSubs

Open gSubs from your applications menu. You’ll see the main interface with a purple gradient background and a drag-and-drop zone in the center.
2

Select your language

Click the language selector in the bottom right corner and choose your preferred subtitle language. gSubs defaults to English.Available 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)
Your language preference is saved automatically and will be remembered for future sessions.
3

Drag and drop your video file

Drag a video file from your file explorer and drop it onto the gSubs window. The interface will show +1 when hovering over the drop zone.Supported formats: .mp4, .avi, .mkv, .mpg, .webm, .m4v
gSubs only accepts video files. If you drop a non-video file, you’ll see a shake animation and an error message: “Only video files are supported”.
4

Wait for subtitle search

gSubs will immediately start searching for subtitles:
  1. First, it checks SubDB using the video file’s hash for an exact match
  2. If no match is found, it performs a deep search on OpenSubtitles using the filename
You’ll see a loading animation with the message “Searching subtitle for [filename]”.
5

Download the subtitle

When gSubs finds a match:For exact matches:
  • The background changes to green
  • A checkmark appears with the message “Subtitle successfully downloaded for [filename]”
  • The subtitle file (.srt) is automatically saved in the same directory as your video
  • A play button appears to open the video with your default player
For multiple matches:
  • The background changes to green
  • A table appears showing all potential subtitle matches
  • Click the download icon next to your preferred subtitle
  • The subtitle will be saved in the same directory as your video
The subtitle file is automatically named to match your video file. For example, movie.mp4 will get a subtitle named movie.srt.

​
Handling multiple files

gSubs can process entire seasons or multiple movies at once.
1

Drop multiple video files

Drag and drop multiple video files (or an entire folder) onto gSubs. The interface will show the total count, like +12 for twelve files.
2

Watch the progress

gSubs displays a table with all your video files and their search status:
  • Loading spinner: Currently searching
  • Green checkmark: Subtitle found and downloaded
  • Red cross: No subtitle found
  • Right arrow: Multiple matches available (click to view options)
3

Review results

Once all files are processed, the background turns green and shows:“Successfully found subtitles for the following videos”Files with a right arrow icon have multiple subtitle options. Click the arrow to view and download your preferred match.
gSubs searches all files in parallel for maximum speed. Processing 10 files takes roughly the same time as processing 1 file.

​
Using the search feature

Don’t have the video file yet? Use gSubs’ search function to find subtitles by name.
1

Enter your search query

Click the search box at the bottom of the gSubs window and type a movie or series name.
2

Press Enter

Hit Enter to start the search. gSubs will query OpenSubtitles for matching subtitles in your selected language.
3

Download from results

gSubs displays a table with all matching subtitles. Click the download icon next to any result.You’ll be prompted to choose a save location (defaults to Desktop).

​
What if no subtitle is found?

If gSubs can’t find a subtitle match:
  1. The background turns red
  2. A sad face icon appears
  3. The message shows: “Couldn’t find subtitle for [filename]”
Troubleshooting tips:
  • Rename your video file to match the official movie/series title
  • Try removing extra information from the filename (resolution, codec, release group)
  • Use the search feature instead to manually find the subtitle
  • Check that your internet connection is working
For TV shows, use the format: Show.Name.S01E01.srt (season and episode numbers help matching accuracy).

​
Deep search feature

When gSubs finds multiple potential matches during drag-and-drop, you can perform a deep search:
  1. Click the right arrow icon next to any file in the results table
  2. gSubs performs an advanced search using OpenSubtitles with multiple parameters:
    • File path hash
    • Exact filename
    • Query by filename
  3. A new table appears with refined subtitle matches
  4. Download your preferred option
// Deep search parameters
OpenSubtitles.search({
  sublanguageid: 'eng',
  path: '/path/to/video.mp4',
  filename: 'video.mp4',
  query: 'video.mp4',
  limit: 'all'
})
Deep search is more thorough but may return more results to choose from. It’s perfect when you need the most accurate subtitle match.

​
Understanding the interface

The gSubs interface uses color-coding to show status:
Background ColorMeaning
Purple gradientHome screen / Ready for input
Purple (loading)Searching for subtitles
Green gradientSuccess / Subtitles found
Red gradientError / No subtitles found
Icons:
  • Home icon: Return to main screen
  • Close icon: Quit gSubs
  • Play icon: Open video with default player
  • Download icon: Download a subtitle
  • Checkmark: Subtitle successfully downloaded
  • Cross: Subtitle search failed
  • Right arrow: View more subtitle options

​
Next steps

Now that you’ve downloaded your first subtitle, explore more features:

Process entire seasons

Drop a folder with multiple episodes to batch process all files at once

Try different languages

Switch between 10 supported languages to find subtitles in your preferred language

Use search for upcoming releases

Search for movie/series subtitles before you have the video file

Automatic updates

Keep gSubs up to date automatically - no manual downloads needed

​
Tips for best results

Name your files clearly: Use standard naming conventions like Movie.Title.2020.mp4 or Show.Name.S01E01.mp4 for best matching accuracy.
Check your language setting: Make sure you’ve selected the correct language before searching. The language preference is saved for future use.
Internet connection required: gSubs needs an active internet connection to search SubDB and OpenSubtitles. Check your connection if searches fail.
The subtitle will be saved in the same directory as your video file. Make sure you have write permissions for that location.

​
Getting help

If you encounter issues or have questions:
  • Check the troubleshooting guide for common issues and solutions
  • Report issues on GitHub Issues
  • Contribute to the project as it’s open-source and welcomes contributions

Build docs developers (and LLMs) love

Get started for freeTalk to us