ToniesViewer Plugin

Overview

The ToniesViewer plugin provides a GUI interface for browsing, searching, and viewing the Tonies database. It integrates seamlessly with the TonieToolbox to display tonie artwork, metadata, and technical details in an intuitive, searchable interface.

Features

• Advanced Search: Search across title, series, model, episodes, audio ID, and hash
• Smart Filtering: Filter by language and category with dropdown menus
• Sortable Table: Click column headers to sort by any field
• Image Preview: High-resolution tonie artwork with automatic caching
• Detailed Information: View complete metadata, audio IDs, hashes, and release dates
• Copy to Clipboard: Quick copy functionality for audio IDs
• Dual Interface: Embedded tab view and external window dialog
• Internationalization: Full i18n support (English and German)

Installation

Via Plugin Manager (Recommended)

1. Launch TonieToolbox GUI: tonietoolbox --gui
2. Open Tools → Plugin Manager
3. Go to Discover tab
4. Search for "Tonies Viewer"
5. Click Install

Manual Installation

cd ~/.tonietoolbox/plugins/
git clone https://github.com/TonieToolbox/plugin_tonies_viewer.git tonies_viewer

After installation, enable the plugin in the Plugin Manager and restart TonieToolbox GUI.

Dependencies

Required Plugins:

• ToniesLoader (com.tonietoolbox.tonies_loader >= 1.0.0) - Provides Tonies database access

The ToniesLoader plugin will be automatically installed as a dependency. When installing via the Plugin Manager, it handles dependencies for you.

Python Requirements:

• PyQt6 (provided by TonieToolbox GUI)

Usage

Opening the Viewer

Embedded Tab View:

• Look for the "Tonies Database" tab in the main TonieToolbox window

External Window:

• Click the external window button (↗) in the tab header
• Opens the viewer in a separate resizable dialog

Searching and Filtering

Search Box:

• Type any text to search across multiple fields:
  • Title
  • Series
  • Model number
  • Episode names
  • Audio IDs
  • Hash values

Language Filter:

• Select a specific language (e.g., "de-de", "en-us")
• Or choose "All Languages" to view all tonies

Category Filter:

• Filter by category (e.g., "Hörspiele & Hörbücher", "Musik")
• Or choose "All Categories" to view all

Sorting:

• Click any column header to sort the table
• Click again to reverse sort order
• Sortable columns: Model, Title, Series, Language, Category, Release

Viewing Details

1. Select a Tonie: Click any row in the table
2. View Details Panel (right side) shows:
   • Image: Tonie artwork (automatically cached)
   • Metadata: Title, series, episode information
   • Technical: Model number, audio IDs, hash values
   • Release Date: When the tonie was released

Copying Audio IDs

1. Select a tonie from the table
2. Click Copy Audio ID button
3. Audio ID is copied to clipboard
4. Use in TeddyCloud, custom tools, or for reference

Screenshots

Tab View

External Dialog

Search and Filtering

Detail View

Configuration

Settings

Cache Images (default: true)

• Automatically cache downloaded tonie images locally
• Reduces network usage and improves performance
• Images cached to ~/.tonietoolbox/cache/tonies_viewer/

Cache Management

Cache Location:

~/.tonietoolbox/cache/tonies_viewer/images/

Clear Cache:

rm -rf ~/.tonietoolbox/cache/tonies_viewer/images/

Images will be re-downloaded on next view.

Architecture

Component Structure

• ToniesViewerWidget: Core functionality (search, filter, display)
• ToniesViewerDialog: Window wrapper for external dialog mode
• ImageLoader: Async image downloading and caching
• Service Integration: Uses ToniesLoader plugin service for data access

Design Patterns

• Composition Pattern: Dialog wraps widget to eliminate code duplication
• Dependency Injection: Services injected via PluginContext
• Event-Driven: Qt signals/slots for UI interactions
• Clean Architecture: Proper separation of concerns

Development

Project Structure

plugin_tonies_viewer/
├── __init__.py              # Plugin exports
├── plugin.py                # Main GUIPlugin implementation
├── manifest.json            # Plugin metadata
├── CHANGELOG.md             # Version history
├── LICENSE.md               # GPL-3.0 license
├── README.md                # This file
├── components/
│   ├── __init__.py
│   ├── viewer_widget.py     # Core viewer widget (embedded/tab mode)
│   ├── viewer_dialog.py     # Dialog wrapper for external window
│   └── image_loader.py      # Async image loader with caching
└── i18n/
    └── translations/
        ├── en_US.json       # English
        └── de_DE.json       # German

Key Components

ToniesViewerPlugin (plugin.py)

• Inherits from GUIPlugin
• Registers tab integration and external window capability
• Manages widget and dialog lifecycle
• Depends on ToniesLoader service

ToniesViewerWidget (components/viewer_widget.py)

• Core browser functionality (search, filter, table, details)
• Can be embedded in tabs or used standalone
• Emits external_window_requested signal
• 504 lines of focused functionality

ToniesViewerDialog (components/viewer_dialog.py)

• Simple wrapper around ToniesViewerWidget
• Adds window chrome (title, close button)
• Only 101 lines thanks to composition pattern
• Eliminates code duplication

ImageLoader (components/image_loader.py)

• Background thread for downloading tonie images
• Uses context.download_and_cache() for efficient caching
• Non-blocking UI during image downloads
• Automatic TTL management

Technical Details

Data Flow

1. Service Access: Retrieves tonies data from ToniesLoader service
2. Data Loading: Calls get_all_v1_tonies() on initialization
3. Filtering: Applies search text and dropdown filters in real-time
4. Table Population: Displays filtered results with sortable columns
5. Image Loading: Downloads and caches artwork on selection
6. Details Display: Shows comprehensive metadata in detail panel

Performance

• Handles 6000+ tonies smoothly with Qt's optimized table widget
• Background image loading prevents UI blocking
• Image caching reduces network usage and improves responsiveness
• Incremental filtering updates table in real-time as user types

Threading

• Main UI runs on Qt main thread
• Image downloads run on separate QThread workers
• Thread-safe signal/slot communication
• Proper cleanup prevents memory leaks

Configuration

The plugin can be configured via ~/.tonietoolbox/config.json:

{
  "plugins": {
    "com.tonietoolbox.tonies_viewer": {
      "cache_images": true
    }
  }
}

Configuration Options

Option	Type	Default	Description
cache_images	boolean	true	Automatically cache downloaded tonie images locally to reduce network usage

Examples

Disable image caching:

{
  "plugins": {
    "com.tonietoolbox.tonies_viewer": {
      "cache_images": false
    }
  }
}

Disable the plugin:

{
  "plugins": {
    "disabled_plugins": ["com.tonietoolbox.tonies_viewer"]
  }
}

Troubleshooting

"ToniesLoader service not available"

Error Dialog: Plugin shows error dialog on missing ToniesLoader service.

Solution: Install the ToniesLoader plugin first:

# Via Plugin Manager (Recommended)
Tools → Plugin Manager → Discover → Search "ToniesLoader" → Install

# Manual Installation
cd ~/.tonietoolbox/plugins/
git clone https://github.com/TonieToolbox/plugin_tonies_loader.git tonies_loader

Images not loading

Possible causes:

• No internet connection
• Firewall blocking image downloads
• Image URLs unavailable

Solutions:

• Check internet connection
• Verify firewall allows TonieToolbox network access
• Check ToniesLoader plugin is working correctly
• Clear image cache and retry: rm -rf ~/.tonietoolbox/cache/tonies_viewer/images/

Plugin not appearing

Solutions:

• Ensure plugin is enabled in Plugin Manager
• Check ToniesLoader plugin is installed and enabled
• Restart TonieToolbox
• Check logs for initialization errors: tonietoolbox --gui --debug

Credits

• Data source: toniebox-reverse-engineering/tonies-json

Support

For issues or questions about the plugin, please open an issue on the TonieToolbox repository.