Metadata-Version: 2.4
Name: GameSentenceMiner
Version: 2.19.13
Summary: A tool for mining sentences from games. Update: Dependencies, replay buffer based line searching, and bug fixes.
Author-email: Beangate <bpwhelan95@gmail.com>
License: MIT License
Project-URL: Homepage, https://github.com/bpwhelan/GameSentenceMiner
Project-URL: Repository, https://github.com/bpwhelan/GameSentenceMiner
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests~=2.32.5
Requires-Dist: watchdog~=6.0.0
Requires-Dist: DateTime~=5.5
Requires-Dist: pyperclip~=1.9.0
Requires-Dist: soundfile~=0.13.1
Requires-Dist: toml~=0.10.2
Requires-Dist: psutil~=7.1.0
Requires-Dist: rapidfuzz~=3.10.0
Requires-Dist: plyer~=2.1.0
Requires-Dist: keyboard~=0.13.5
Requires-Dist: websockets~=15.0.1
Requires-Dist: ttkbootstrap~=1.10.1
Requires-Dist: dataclasses_json~=0.6.7
Requires-Dist: betterproto==2.0.0b7
Requires-Dist: obsws-python~=1.8.0
Requires-Dist: numpy==2.2.6
Requires-Dist: faster-whisper~=1.2.0
Requires-Dist: silero-vad~=6.0.0
Requires-Dist: regex~=2025.10.23
Requires-Dist: opencv-python~=4.12.0.88
Requires-Dist: scikit-image~=0.25.2
Requires-Dist: owocr==1.9.1
Requires-Dist: oneocr==1.0.10
Requires-Dist: google-genai~=1.46.0
Requires-Dist: sounddevice~=0.5.2
Requires-Dist: matplotlib~=3.10.6
Requires-Dist: groq~=0.33.0
Requires-Dist: flask~=3.1.2
Requires-Dist: pystray~=0.19.5
Requires-Dist: pygetwindow==0.0.9; sys_platform == "win32"
Requires-Dist: pywin32==311; sys_platform == "win32"
Requires-Dist: win10toast==0.9; sys_platform == "win32"
Requires-Dist: stable-ts~=2.19.1
Requires-Dist: torchcodec~=0.7.0
Requires-Dist: torchaudio==2.8.0
Requires-Dist: pillow~=12.0.0
Requires-Dist: openai~=2.6.0
Requires-Dist: pynput~=1.8.1
Dynamic: license-file

# GSM - An Immersion toolkit for Games.

### English | [日本語](docs/ja/README.md) | [简体中文](docs/zh/README.md).

An application designed to assist with language learning through games.

Short Demo (Watch this first): https://www.youtube.com/watch?v=FeFBL7py6HY

Installation: https://www.youtube.com/watch?v=sVL9omRbGc4

Discord: https://discord.gg/yP8Qse6bb8

## Features - [Anki Card Enhancement](#anki-card-enhancement) | [OCR](#ocr) | [Overlay](#overlay)

### Anki Card Enhancement

GSM significantly enhances your Anki cards with rich contextual information:

* **Automated Audio Capture**: Automatically records the voice line associated with the text.

  * **Automatic Trim**: Some simple math around the time that the text event came in, in combination with a "Voice Activation Detection" (VAD) library gives us neatly cut audio.
  * **Manual Trim**: If Automatic voiceline trim is not perfect, it's possible to [open the audio in an external program](https://youtu.be/LKFQFy2Qm64) for trimming.

* **Screenshot**: Captures a screenshot of the game at the moment the voice line is spoken.

* **Multi-Line**: It's possible to capture multiple lines at once with sentence audio with GSM's very own Texthooker.

* **AI Translation**: Integrates AI to provide quick translations of the captured sentence. Custom Prompts also supported. (Optional, Bring your own Key)


#### Game Example (Has Audio)

https://github.com/user-attachments/assets/df6bc38e-d74d-423e-b270-8a82eec2394c

---

#### VN Example (Has Audio)

https://github.com/user-attachments/assets/ee670fda-1a8b-4dec-b9e6-072264155c6e

---

### OCR

GSM runs a fork of [OwOCR](https://github.com/AuroraWright/owocr/) to provide accurate text capture from games that do not have a hook. Here are some improvements GSM makes on stock OwOCR:

* **Easier Setup**: With GSM's managed Python install, setup is only a matter of clicking a few buttons.

* **Exclusion Zones**: Instead of choosing an area to OCR, you can choose an area to exclude from OCR. Useful if you have a static interface in your game and text appears randomly throughout.

* **Two-Pass OCR**: To cut down on API calls and keep output clean, GSM features a "Two-Pass" OCR System. A Local OCR will be constantly running, and when the text on screen stabilizes, it will run a second, more accurate scan that gets sent to clipboard/WebSocket.

* **Consistent Audio Timing**: With the two-pass system, we can still get accurate audio recorded and into Anki without the use of crazy offsets or hacks.

* **More Language Support**: Stock OwOCR is hard-coded to Japanese, while in GSM you can use a variety of languages.


https://github.com/user-attachments/assets/07240472-831a-40e6-be22-c64b880b0d66

---

### Overlay

GSM also features an overlay that allows for on-screen yomitan lookups. Whenever the overlay is on it will scan the screen ONCE whenever a text event from any source comes into GSM. It then allows for hovering over the actual characters in-game for yomitan lookups, and mining.

https://youtu.be/m1MweBsHbwI

![l0qGasWkoH](https://github.com/user-attachments/assets/c8374705-efa0-497b-b979-113fae8a1e31)

<!--### Game Launcher Capabilities (WIP)

This is probably the feature I care least about, but if you are lazy like me, you may find this helpful.

* **Launch**:  GSM can launch your games directly, simplifying the setup process.

* **Hook**:  Streamlines the process of hooking your games (Agent).

This feature simplifies the process of launching games and (potentially) hooking them, making the entire workflow more efficient.

<img width="2560" height="1392" alt="GameSentenceMiner_1zuov0R9xK" src="https://github.com/user-attachments/assets/205769bb-3dd2-493b-9383-2d6e2ca05c2d" />-->

## Basic Requirements

* **Anki card creation tool**: [Yomitan](https://github.com/yomidevs/yomitan), [JL](https://github.com/rampaa/JL), etc.

* **A method of getting text from the game**: [Agent](https://github.com/0xDC00/agent), [Textractor](https://github.com/Artikash/Textractor), [LunaTranslator](https://github.com/HIllya51/LunaTranslator), GSM's OCR, etc.

* **A game :)**

## Documentation

For help with installation, setup, and other information, please visit the project's [Wiki](https://github.com/bpwhelan/GameSentenceMiner/wiki).

## FAQ

### How Does It Work?

This is a common question, and understanding this process will help clarify any issues you might encounter while using GSM.

1.  The beginning of the voice line is marked by a text event. This usually comes from Textractor, Agent, or another texthooker. GSM can listen for a clipboard copy and/or a WebSocket server (configurable in GSM).

2.  The end of the voice line is detected using a Voice Activity Detection (VAD) library running locally. ([Example](https://github.com/snakers4/silero-vad))

In essence, GSM relies on accurately timed text events to capture the corresponding audio.

GSM provides settings to accommodate less-than-ideal hooks. However, if you experience significant audio inconsistencies, they likely stem from a poorly timed hook, loud background music, or other external factors, rather than GSM itself. The core audio trimming logic has been stable and effective for many users across various games.

## Contact

If you encounter issues, please ask for help in my [Discord](https://discord.gg/yP8Qse6bb8) or create an issue here.

## Acknowledgements

* [OwOCR](https://github.com/AuroraWright/owocr) for their outstanding OCR implementation, which I've integrated into GSM.

* [chaiNNer](https://github.com/chaiNNer-org/chaiNNer) for the idea of installing Python within an Electron app.

* [OBS](https://obsproject.com/) and [FFMPEG](https://ffmpeg.org/), without which GSM would not be possible.

* [Renji's Texthooker](https://github.com/Renji-XD/texthooker-ui)

* https://github.com/Saplling/transparent-texthooker-overlay

* [exSTATic](https://github.com/KamWithK/exSTATic) for inspiration for GSM's Stats.

* [Kanji Grid](https://github.com/Kuuuube/kanjigrid)

## Donations

If you've found this or any of my other projects helpful, please consider supporting my work through [GitHub Sponsors](https://github.com/sponsors/bpwhelan), or [Ko-fi](https://ko-fi.com/beangate).

