如果你只是想正常使用插件，请在这里下载：Fully Automatic Installation

• 【PotPlayer AI 翻译插件安装教程 - 哔哩哔哩】 https://b23.tv/ntF2dxu

简体中文 | 繁體中文 | English

DolOffer - 一站式数字订阅充值平台

主营 GPT、Claude 等 AI 服务会员正版订阅充值。
💰 使用折扣码：AI8888
🚀 极速发货，售后无忧。

PotPlayer_ChatGPT_Translate 🚀

A PotPlayer subtitle translation plugin powered by OpenAI-compatible AI APIs.
It translates subtitles in real time and can use subtitle context to improve accuracy.

Works on my machine — but bug reports are welcome.

Download Latest Release  ·  Report Bug  ·  Request Feature

---

Important Notice

The source-code version of this project is mainly for development and testing. It is not currently designed as the recommended installation method for normal users, and not every source-code path has been fully tested.

If you only want to use the plugin, please install it from the release package:

Recommended download: Fully Automatic Installation

The repository was temporarily unavailable for a period of time because my GitHub account was suspended. The project is now available again.

Video tutorial:

• Bilibili: PotPlayer AI Translation Plugin Installation Tutorial

---

Table of Contents

1. What This Project Does
2. Features
3. Installation
   • Fully Automatic Installation Recommended
   • Manual Installation
4. Configuration Reference
5. Available Model Examples
6. Usage
7. Translation Examples
8. Video Tutorial
9. Logic Flowchart
10. Built With
11. Roadmap
12. Contributing
13. License
14. Contact
15. Acknowledgments

---

What This Project Does

PotPlayer_ChatGPT_Translate is a subtitle translation plugin for PotPlayer.

It sends subtitle text to an AI model through an OpenAI-compatible API endpoint and returns translated subtitles directly inside PotPlayer. Compared with traditional subtitle translation tools, AI models can often handle context, idioms, jokes, cultural references, and ambiguous dialogue more naturally.

The plugin provides two main script variants:

• With context: uses previous subtitles as context. Translation quality is usually better, but latency and token usage may be higher.
• Without context: translates each subtitle more independently. It is faster and cheaper, but may misunderstand pronouns, references, jokes, or short lines.

This project is not limited to OpenAI models. Any model or service that follows a compatible chat/completions API format can potentially be used.

(back to top)

---

Features

• Real-time subtitle translation inside PotPlayer.
• Context-aware translation mode.
• No-context translation mode for faster requests.
• OpenAI-compatible API support.
• Custom API base URL support.
• API-key and no-key endpoint support.
• Optional retry behavior.
• Optional request delay.
• Optional context cache mode.
• Optional small-model prompt mode.
• Optional hallucination check for abnormal translation output.
• Installer-based automatic setup.
• Manual installation support.

(back to top)

---

Installation

Fully Automatic Installation Recommended

This is the recommended method for normal users.

1. Download the latest installer from:

   Latest Release

2. Run installer.exe.

3. Approve the Windows administrator prompt if it appears.

4. Confirm the PotPlayer plugin folder.

   The installer will try to detect your PotPlayer path automatically. The target folder should usually be:

   ...\PotPlayer\Extension\Subtitle\Translate
   

   If PotPlayer is installed in a custom location, manually select the correct Translate folder.

5. Choose the plugin variant.

   • With context: better translation quality, slightly higher latency and token usage.
   • Without context: faster, cheaper, but less context-aware.

6. Configure the model and API endpoint.

   Example model field:

   gpt-4.1-nano
   

   Example with custom API endpoint:

   gpt-4.1-nano|https://api.openai.com/v1/chat/completions
   

7. Enter your API key if required.

   If your API endpoint does not require a key, leave the key field blank and use Verify. If the empty-key test succeeds, the installer will automatically inject nullkey.

8. Click Install.

   The installer will copy the required plugin files into PotPlayer’s subtitle translation extension folder. You may also register the uninstaller entry so the plugin can be removed cleanly later.

After installation, check the plugin inside PotPlayer:

1. Open PotPlayer.
2. Press F5 to open Preferences.
3. Go to Extensions > Subtitle translation.
4. Select ChatGPT Translate.
5. Set the source and target languages.
6. Confirm the model, API URL, and API key settings.

Installer defaults are written once. If you later change settings inside PotPlayer’s plugin panel, PotPlayer’s own settings will override the installer defaults.

(back to top)

---

Manual Installation

Manual installation is mainly intended for advanced users.

1. Download the latest ZIP package from the repository or release page.

2. Extract the ZIP file.

3. Copy the plugin files into PotPlayer’s subtitle translation extension folder:

   C:\Program Files\DAUM\PotPlayer\Extension\Subtitle\Translate
   

   If your PotPlayer is installed somewhere else, replace the path with your actual PotPlayer installation path.

4. Copy the required files:

   ChatGPTSubtitleTranslate.as
   ChatGPTSubtitleTranslate.ico
   

5. Open PotPlayer Preferences by pressing F5.

6. Go to:

   Extensions > Subtitle translation
   

7. Select ChatGPT Translate.

8. Configure the model name, API URL, API key, source language, and target language.

Important:

If you switch between the context-aware script and the no-context script, replace the related .as files together.

Older script copies may use shared helper names such as FormatFailureTranslation, which can cause PotPlayer to report a conflict depending on which script loads first. Current files use uniquely prefixed helpers to avoid this issue.

(back to top)

---

Configuration Reference

The plugin mainly uses the Model Name field and the API Key field.

Basic Model Name

If you only enter a model name, the plugin uses the default API URL configured by the script or installer.

gpt-4.1-nano

Custom API Base URL

Use this format:

ModelName|API Base URL

Example:

gpt-4.1-nano|https://api.openai.com/v1/chat/completions

No-Key Endpoint

If your endpoint does not require an API key, add nullkey.

ModelName|API Base URL|nullkey

Example for local deployment:

qwen2.5:7b|http://127.0.0.1:11434/v1/chat/completions|nullkey

You can also use a model name with nullkey directly:

gpt-4.1-nano|nullkey

This is useful when the installer or script already knows the default endpoint.

Optional Parameters

You can append optional parameters after the model and API URL. Each option is separated by |.

Full format:

ModelName|API Base URL|nullkey|delay_ms|retryN|context=3|cache=auto/off|smallmodel=0/1|checkhallucination=0/1

Available options:

Option	Meaning
nullkey	Use this when the endpoint does not require an API key.
delay_ms	Digits only. Adds a delay before requests or retries depending on retry mode.
retry0	No retry.
retry1	Retry once when the response is empty.
retry2	Keep retrying until a response is returned, without delay.
retry3	Keep retrying until a response is returned, with delay before every attempt.
context=3	Context version only. Number of recent subtitle entries to send as context. Use 0 to send no previous subtitles.
cache=auto	Enable context cache mode when available. Context version only. Falls back to normal chat mode if unsupported.
cache=off	Disable context cache mode.
smallmodel=0	Disable small-model prompt mode.
smallmodel=1	Enable prompt mode optimized for smaller models.
checkhallucination=0	Disable hallucination-length check.
checkhallucination=1	Retry if the translated output is more than 5 times longer than the source subtitle.

Example with several options:

gpt-4.1-nano|https://api.openai.com/v1/chat/completions|nullkey|500|retry1|context=3|cache=auto|smallmodel=1|checkhallucination=1

API Key

Enter your API key in the API key field if your endpoint requires one.

If your endpoint does not require a key:

1. Leave the key field blank.
2. Click Verify.
3. If verification succeeds, the installer will inject nullkey.

You can optionally test your API key here:

keytest.obanarchy.org

(back to top)

---

Available Model Examples

These are examples only. Actual availability depends on your API provider, account access, endpoint compatibility, and model naming rules.

Use this general format:

ModelName|API Base URL|nullkey(optional)|delay_ms(optional)|retryN(optional)|context=3(optional)|cache=auto/off(optional)|smallmodel=0/1(optional)|checkhallucination=0/1(optional)

OpenAI-Compatible Examples

OpenAI GPT-5: gpt-5|https://api.openai.com/v1/chat/completions
OpenAI GPT-5 Mini: gpt-5-mini|https://api.openai.com/v1/chat/completions
OpenAI GPT-5 Nano: gpt-5-nano|https://api.openai.com/v1/chat/completions
OpenAI GPT-4.1: gpt-4.1|https://api.openai.com/v1/chat/completions
OpenAI GPT-4.1 Mini: gpt-4.1-mini|https://api.openai.com/v1/chat/completions
OpenAI GPT-4o: gpt-4o|https://api.openai.com/v1/chat/completions
OpenAI GPT-4 Turbo: gpt-4-turbo|https://api.openai.com/v1/chat/completions
OpenAI GPT-3.5 Turbo: gpt-3.5-turbo|https://api.openai.com/v1/chat/completions

Other Cloud Provider Examples

Gemini Flash: gemini-3-flash-preview|https://generativelanguage.googleapis.com/v1beta/openai/chat/completions
Gemini 2.0 Flash: gemini-2.0-flash|https://generativelanguage.googleapis.com/v1beta/openai/chat/completions
DeepSeek Chat: deepseek-chat|https://api.deepseek.com/v1/chat/completions
Tongyi Qianwen: qwen-plus|https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions
SiliconFlow: siliconflow-chat|https://api.siliconflow.cn/v1/chat/completions
ERNIE Bot: ernie-4.0-turbo-8k|https://qianfan.baidubce.com/v2/chat/completions
Moonshot v1: moonshot-v1-128k|https://api.moonshot.cn/v1/chat/completions
Yi 34B Chat: yi-34b-chat|https://api.lingyi.ai/v1/chat/completions
Mistral Large: mistral-large|https://api.mistral.ai/v1/chat/completions
Groq Llama 3: llama3-70b-8192|https://api.groq.com/openai/v1/chat/completions
Fireworks Mixtral: accounts/fireworks/models/mixtral-8x7b-instruct|https://api.fireworks.ai/inference/v1/chat/completions
Perplexity Sonar Large: pplx-70b-online|https://api.perplexity.ai/chat/completions

Local Deployment Example

For local OpenAI-compatible services, use nullkey if no API key is required.

model-name|http://127.0.0.1:PORT/v1/chat/completions|nullkey

Example:

qwen2.5:7b|http://127.0.0.1:11434/v1/chat/completions|nullkey

Model names shown in the installer may be localized when possible. You can replace the examples above with any compatible model supported by your API provider.

(back to top)

---

Usage

After installation and configuration, play a video with subtitles in PotPlayer.

The plugin will automatically send subtitle text to the configured AI endpoint and return translated subtitles in real time.

For best results:

• Use the context-aware version for movies, TV shows, anime, documentaries, and dialogue-heavy content.
• Use the no-context version when speed and lower token usage matter more than contextual accuracy.
• Use a smaller or cheaper model if you translate large amounts of subtitles.
• Use a stronger model if the content contains jokes, slang, cultural references, technical terms, or complicated dialogue.
• Enable checkhallucination=1 if your model sometimes produces abnormally long output.
• Add a request delay if your API provider has strict rate limits.

(back to top)

---

Translation Examples

Google Translate vs AI Translation

Original subtitle:

You're gonna old yeller my f**king universe.

Google Translate result:

你要老了我他妈的宇宙吗?

This translation is literal and does not understand the cultural reference.

AI translation result:

你要像《老黄犬》一样对待我的宇宙?

This result captures the reference to Old Yeller and produces a more meaningful subtitle.

---

Without Context vs With Context

Original subtitle:

But being one in real life is even better.

AI translation without context:

但是，在现实生活中成为一个人甚至更好。

This translation is grammatically valid but misses what “one” refers to.

AI translation with context:

但在现实生活中成为一个反派更好。

With previous subtitle context, the model can infer the intended meaning more accurately.

(back to top)

---

Video Tutorial

Click the image below to watch the installation tutorial on Bilibili:

Alternative short link:

https://b23.tv/ntF2dxu

(back to top)

---

Logic Flowchart

Show logic flowchart

graph TD
    Start([Start: Translate]) --> InitConfig[Load Config and Token Rules]
    InitConfig --> CheckAuth{API Key Configured?}
    CheckAuth -- No --> RetError([Return Error Message])
    CheckAuth -- Yes --> UpdateHist[Update Subtitle History]

    UpdateHist --> ContextMode{Plugin Variant?}

    subgraph ContextLogic [Context Processing]
        direction TB
        ContextMode -- "Without Context" --> NoContextPrompt[No Context]
        ContextMode -- "With Context" --> ReadCount[Read Subtitle Count Setting]
        ReadCount --> TrimHist[Keep Recent History]
        TrimHist --> BuildBlock["Build Context Block\nup to configured recent lines"]
    end

    subgraph PromptEng [Prompt Construction]
        direction TB
        BuildBlock --> SmallModel{Small Model Mode?}
        NoContextPrompt --> SmallModel

        SmallModel -- Yes --> StrictPrompt[System Instructions + User <CONTEXT>/<CURRENT> Tags]
        SmallModel -- No --> StdPrompt[System Instructions + User <CONTEXT>/<CURRENT> Tags]

        StrictPrompt --> EscapeJSON[Escape JSON Strings]
        StdPrompt --> EscapeJSON
        EscapeJSON --> BuildPayload[Build JSON Payload]
    end

    BuildPayload --> InitLoop[Initialize Retry Counter]

    subgraph RetrySystem [Execution and Retry Loop]
        direction TB
        LoopCond{Attempts <= Max?}
        LoopCond -- No --> FailFinal([Return Failure Message])

        LoopCond -- Yes --> DelayCheck{Delay Required?}
        DelayCheck -- Yes --> Wait[Sleep Configured Delay]
        DelayCheck -- No --> CacheBranch
        Wait --> CacheBranch

        CacheBranch{Cache Mode Enabled?}
        CacheBranch -- Yes --> ReqCache[POST /responses]
        CacheBranch -- No --> ReqChat[POST /chat/completions]

        ReqCache --> RespCache{Response OK?}
        RespCache -- Yes --> ParseCache[Extract output_text]
        RespCache -- No --> LogCacheFail[Log Cache Failure]
        LogCacheFail --> ReqChat

        ParseCache --> HallucinationCheck

        ReqChat --> NetCheck{Network OK?}
        NetCheck -- No --> IncRetry[Attempts + 1]
        IncRetry --> LoopCond

        NetCheck -- Yes --> ParseJSON{Valid JSON?}
        ParseJSON -- No --> IncRetry
        ParseJSON -- Error --> LogAPIError[Log API Error]
        LogAPIError --> IncRetry
        ParseJSON -- Success --> ExtractContent[Extract Content]

        ExtractContent --> HallucinationCheck{Hallucination Check?}

        HallucinationCheck -- "Output too long" --> LogHallu[Log Hallucination Warning]
        LogHallu --> IncRetry

        HallucinationCheck -- OK --> SuccessBreak[Break Loop]
    end

    SuccessBreak --> PostProc[Post Processing]
    PostProc --> FixNewlines[Trim Trailing Newlines]
    FixNewlines --> FixRTL[Fix RTL Languages]
    FixRTL --> ReturnSuccess([Return Translation])

Loading

(back to top)

---

Built With

• AngleScript: plugin scripting language.
• PotPlayer Extension API: integration with PotPlayer subtitle translation.
• OpenAI-compatible APIs: translation model backend.
• Installer: automatic deployment and configuration for normal users.

(back to top)

---

Roadmap

• Integrate AI subtitle translation with PotPlayer.
• Add context-aware translation.
• Add no-context translation mode.
• Add installer-based automatic setup.
• Add no-key endpoint support.
• Add retry and delay options.
• Add small-model prompt mode.
• Add hallucination-length check.
• Improve compatibility with more OpenAI-compatible providers.
• Improve configuration UI and error messages.
• Optimize context handling and token usage.
• Add more troubleshooting documentation.

(back to top)

---

Contributing

Contributions are welcome.

Before submitting a pull request, please make sure your change has a clear purpose. For larger changes, it is better to open an issue first so the design can be discussed.

Good contribution areas include:

• Bug fixes.
• Provider compatibility fixes.
• Installer improvements.
• Documentation improvements.
• Translation prompt improvements.
• Better error messages.
• More reliable configuration parsing.

When reporting a bug, please include:

• PotPlayer version.
• Plugin version.
• Windows version.
• Model name.
• API provider or endpoint type.
• Whether you are using the context or no-context script.
• Error message or screenshot if available.
• Steps to reproduce the issue.

Please do not include private API keys in issues, screenshots, logs, or pull requests.

(back to top)

---

License

Distributed under the GPLv3 License.

See LICENSE for more information.

(back to top)

---

Contact

Personal website:

obanarchy.org

GitHub:

Felix3322

(back to top)

---

Acknowledgments

• Thanks to the PotPlayer team for creating PotPlayer.
• Thanks to OpenAI and other AI model providers for making modern language models available through APIs.
• Thanks to users who test the plugin, report bugs, suggest improvements, and contribute code.

(back to top)

---

Star History

---