Advanced Usage

If you want to dig a bit deeper into what the plugin can do, here are a few extra features.

Gestures

You can tie the X-Ray menu to any of KOReader's gestures (like corner taps or edge swipes):

1. Go to Settings Menu → Taps and Gestures → Gesture Manager.
2. Pick whatever gesture you prefer.
3. Look for X-Ray Quick Menu under General in the action list and assign it.

Manual Config Editing

While most settings are handled through the UI, you can manually enter your API keys by editing xray_config.lua in the plugin folder. It should look like this:

-- X-Ray API Configuration

return {
    -- Google Gemini API Key
    -- To get an API key: https://aistudio.google.com/
    gemini_api_key = "", 
    
    -- ChatGPT API Key 
    -- To get an API key: https://platform.openai.com/api-keys
    chatgpt_api_key = "",  

    -- DeepSeek API Key
    -- To get an API key: https://platform.deepseek.com/
    deepseek_api_key = "",

    -- Anthropic Claude API Key
    -- To get an API key: https://console.anthropic.com/
    claude_api_key = "",

    -- Custom API slot 1 (e.g., OpenRouter, any OpenAI-compatible endpoint)
    custom1_api_key  = "",   -- Your API key for this endpoint
    custom1_endpoint = "",   -- e.g., "https://openrouter.ai/api/v1/chat/completions"
    custom1_model    = "",   -- e.g., "google/gemini-2.5-pro"
    custom1_format   = "",   -- optional: "openai" or "anthropic" (default: auto-detected from endpoint)

    -- Custom API slot 2 (e.g., a local Ollama server)
    custom2_api_key  = "",
    custom2_endpoint = "",   -- e.g., "http://localhost:11434/v1/chat/completions"
    custom2_model    = "",   -- e.g., "llama3"
    custom2_format   = "",   -- optional: "openai" or "anthropic" (default: auto-detected from endpoint)
}

Note: Other settings like model selection and spoiler preferences are managed through the on-screen menu and stored in a separate settings.json file outside the plugin folder, so your settings will persist even if you uninstall and reinstall the plugin.

Maintenance Tools

Under the Maintenance menu, you'll find a few useful utilities:

• Clear Cache: Sometimes the AI gets confused or returns weird data. Hit this to wipe the saved file for your current book and start fresh.
• View Log: Opens the plugin's xray.log file in a scrollable viewer directly inside KOReader — no file manager needed. The viewer automatically scrolls to the bottom so the most recent entries are immediately visible. This is the fastest way to see what the plugin is doing or to diagnose a problem.
• Clear Logs: Deletes both the current log (xray.log) and its backup (xray.log.old). Useful if you want a clean slate before reproducing an issue. The log is also rotated automatically once it exceeds 512 KB, so it won't grow unbounded even if you never manually clear it.
• Beta Channel: Opt into pre-release builds to test the latest features before they are officially released.

Adding New Languages

The plugin natively supports 13 languages (English, German, French, Spanish, Brazilian Portuguese, Russian, Ukrainian, Turkish, Simplified Chinese, Dutch, Hungarian, Polish, and Indonesian). If your language isn't supported yet, you can request it in the Github Issues and we can add additional languages, or you can easily add it yourself! The plugin requires two separate translation files:

1. UI Strings (languages/<lang>.po): This handles the buttons, menus, and messages. You can use en.po as a template and translate the msgstr values.
2. AI Prompts (prompts/<lang>.lua): This is crucial because it tells the AI to provide descriptions and summaries in your language. Without this, the AI may respond in English even if the UI is localized.

Once you've created these files, the plugin will automatically detect them in the Tools Menu → X-Ray → Language settings.