Initial release of MbetterClient v1.0.0

- Complete cross-platform multimedia client application
- PyQt5 video player with dynamic overlay templates
- Flask web dashboard with JWT authentication
- REST API client with configurable endpoints
- Multi-threaded architecture with Queue-based messaging
- SQLite database with automatic migrations
- PyInstaller build configuration for executables
- Comprehensive documentation and build scripts
- Offline-first design with local asset fallbacks

.gitignore

+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Project specific
+config/
+logs/
+videos/
+*.db
+*.sqlite
+*.sqlite3
+data/
+temp/
+build_output/
\ No newline at end of file

CHANGELOG.md

+# Changelog
+
+All notable changes to MbetterClient will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2025-01-19
+
+### Added
+- Initial release of MbetterClient
+- PyQt5 video player with hardware acceleration support
+- Dynamic overlay system with three built-in templates:
+  - News template with scrolling ticker
+  - Sports template with live scores
+  - Simple template for basic text overlays
+- Flask-based web dashboard with modern UI
+- JWT authentication with role-based access control
+- User management system with admin and regular user roles
+- API token management for secure API access
+- REST API client with configurable endpoints
+- Automatic retry logic and error handling for API requests
+- Built-in response handlers for news and sports APIs
+- SQLite database with automatic schema migrations
+- Multi-threaded architecture with Queue-based message passing
+- Cross-platform executable generation with PyInstaller
+- Offline-first design with local asset fallbacks
+- Comprehensive configuration management
+- Real-time system status monitoring
+- Application logging with rotation and filtering
+- Command-line interface with multiple options
+- Web-based configuration interface
+- Template-based video overlays with real-time data
+- Fullscreen video playback support
+- Video control via web dashboard and keyboard shortcuts
+
+### Security
+- Password hashing with salt
+- Secure session management
+- CSRF protection for web forms
+- JWT token expiration and refresh
+- API rate limiting and validation
+- Secure configuration file handling
+
+### Performance
+- Hardware-accelerated video playback
+- Efficient message bus with priority handling
+- Lazy loading of video codecs
+- Optimized database queries with connection pooling
+- Memory-efficient overlay rendering
+- Compressed static assets for web dashboard
+
+### Documentation
+- Complete user documentation
+- API reference with examples
+- Development guide with contribution guidelines
+- Troubleshooting guide
+- Build and deployment instructions
+- Code examples and tutorials
+
+### Supported Platforms
+- Windows 10 and later
+- macOS 10.14 and later  
+- Linux (Ubuntu 18.04+, CentOS 7+, Debian 10+)
+
+### Dependencies
+- Python 3.8+
+- PyQt5 5.15.10
+- Flask 3.0.3
+- SQLAlchemy 2.0.25
+- Requests 2.31.0
+- PyInstaller 6.3.0
+- And other dependencies listed in requirements.txt
+
+### Known Issues
+- Large video files may cause memory issues on systems with < 1GB RAM
+- Some video codecs require additional system libraries on Linux
+- Windows Defender may flag executables built with PyInstaller
+
+### Migration Notes
+- This is the initial release, no migration required
+- Default admin credentials must be changed on first login
+- Configuration files are created automatically on first run
+
+## [Future Releases]
+
+### Planned Features
+- Plugin system for custom extensions
+- Advanced video effects and transitions
+- WebRTC streaming support
+- Mobile device remote control
+- Multi-monitor support with independent overlays
+- Cloud configuration synchronization
+- Advanced analytics and reporting
+- Integration with popular streaming platforms
+- Real-time collaboration features
+- Advanced template editor with drag-and-drop interface
+
+### Potential Breaking Changes
+- Configuration file format may change in v2.0
+- Message bus API may be redesigned for better performance
+- Database schema updates may require manual migration
+- Web dashboard API may be versioned for backward compatibility
+
+---
+
+## Version History
+
+| Version | Release Date | Notes |
+|---------|-------------|--------|
+| 1.0.0   | 2025-01-19  | Initial release |
+
+## Support Policy
+
+- **Current Version (1.x)**: Full support with bug fixes and security updates
+- **Previous Versions**: Security updates only for 6 months after new major release
+- **LTS Versions**: Will be designated for enterprise users starting with v2.0
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.
+
+## License
+
+This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.
\ No newline at end of file

LICENSE

+MIT License
+
+Copyright (c) 2025 MBetter Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
\ No newline at end of file

README.md

+# MbetterClient
+
+A cross-platform multimedia client application with video playback, web dashboard, and REST API integration.
+
+## Features
+
+- **PyQt Video Player**: Fullscreen video playback with customizable overlay templates
+- **Web Dashboard**: Authentication, user management, and configuration interface
+- **REST API Client**: Configurable external API integration with automatic retry
+- **Multi-threaded Architecture**: Four threads with Queue-based message passing
+- **Offline Capability**: Works seamlessly without internet connectivity
+- **Cross-Platform**: Supports Windows, Linux, and macOS
+- **Single Executable**: Built with PyInstaller for easy deployment
+
+## Architecture
+
+The application consists of four main threads:
+
+1. **PyQt Thread**: Video player with overlay rendering
+2. **Web Dashboard Thread**: Flask-based web interface
+3. **REST API Client Thread**: External API communication
+4. **Main Loop Thread**: Inter-thread message coordination
+
+## Quick Start
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://git.nexlab.net/mbetter/mbetterc.git
+cd mbetterc
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+### Running the Application
+
+```bash
+# Run in fullscreen mode (default)
+python main.py
+
+# Run in windowed mode
+python main.py --no-fullscreen
+
+# Show help
+python main.py --help
+```
+
+### Building Executable
+
+```bash
+# Build for current platform
+python build.py
+
+# The executable will be in dist/ directory
+```
+
+## Configuration
+
+Configuration is stored in SQLite database with automatic versioning. Access the web dashboard at `http://localhost:5001` (default) to configure:
+
+- Video overlay templates
+- REST API endpoints and tokens
+- User authentication
+- System settings
+
+## Development
+
+### Project Structure
+
+```
+mbetterc/
+├── main.py                 # Application entry point
+├── requirements.txt        # Python dependencies
+├── build.py               # PyInstaller build script
+├── mbetterclient/         # Main application package
+│   ├── __init__.py
+│   ├── config/            # Configuration management
+│   ├── database/          # SQLite database and models
+│   ├── qt_player/         # PyQt video player
+│   ├── web_dashboard/     # Flask web interface
+│   ├── api_client/        # REST API client
+│   ├── core/              # Main loop and message handling
+│   └── utils/             # Utility functions
+├── assets/                # Static assets (images, templates)
+├── templates/             # Video overlay templates
+├── tests/                 # Unit tests
+└── docs/                  # Documentation
+```
+
+### Message System
+
+Threads communicate via Python Queues with structured messages:
+
+```python
+{
+    "type": "VIDEO_PLAY",
+    "data": {
+        "file_path": "/path/to/video.mp4",
+        "template": "news_template",
+        "overlay_data": {...}
+    },
+    "timestamp": 1234567890.123,
+    "sender": "web_dashboard"
+}
+```
+
+## API Documentation
+
+### Web Dashboard API
+
+- `POST /auth/login` - User authentication
+- `GET /api/tokens` - List JWT tokens
+- `POST /api/tokens` - Create new token
+- `DELETE /api/tokens/{id}` - Delete token
+- `GET /api/config` - Get configuration
+- `PUT /api/config` - Update configuration
+
+### Message Types
+
+#### Video Control
+- `VIDEO_PLAY` - Start video playback
+- `VIDEO_PAUSE` - Pause video
+- `VIDEO_STOP` - Stop video
+- `VIDEO_PROGRESS` - Progress update from player
+
+#### API Client
+- `API_REQUEST` - Make external API request
+- `API_RESPONSE` - Response from external API
+- `API_ERROR` - API request error
+
+#### Configuration
+- `CONFIG_UPDATE` - Configuration changed
+- `TEMPLATE_CHANGE` - Video template changed
+
+## License
+
+Copyright (c) 2025 MBetter Project. All rights reserved.
+
+## Support
+
+For support and documentation, visit the project repository.
\ No newline at end of file

assets/boxing_athletes.png

+# This is a placeholder for the boxing athletes image
+# In a real implementation, this would be a PNG image file
+# For now, we'll create a simple text file to represent the asset
+
+PLACEHOLDER: Boxing Athletes Image
+- Two black athletes boxing
+- Size: 110x110 pixels
+- Format: PNG with transparency
+- Used in news template overlay
\ No newline at end of file

build.bat

+@echo off
+REM Build script for Windows
+
+echo 🚀 MbetterClient Build Script
+echo =============================
+
+REM Check if Python is available
+python --version >nul 2>&1
+if %errorlevel% neq 0 (
+    echo ❌ Python is required but not installed.
+    pause
+    exit /b 1
+)
+
+REM Check if virtual environment exists
+if not exist "venv" (
+    echo ⚠️  Virtual environment not found. Creating one...
+    python -m venv venv
+)
+
+REM Activate virtual environment
+echo 🔧 Activating virtual environment...
+call venv\Scripts\activate.bat
+
+REM Install/upgrade dependencies
+echo 📦 Installing dependencies...
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+
+REM Run the build script
+echo 🔨 Starting build process...
+python build.py
+
+echo ✅ Build script completed!
+pause
\ No newline at end of file

build.sh

+#!/bin/bash
+# Build script for Unix systems (Linux/macOS)
+
+echo "🚀 MbetterClient Build Script"
+echo "============================="
+
+# Check if Python 3 is available
+if ! command -v python3 &> /dev/null; then
+    echo "❌ Python 3 is required but not installed."
+    exit 1
+fi
+
+# Check if virtual environment exists
+if [ ! -d "venv" ]; then
+    echo "⚠️  Virtual environment not found. Creating one..."
+    python3 -m venv venv
+fi
+
+# Activate virtual environment
+echo "🔧 Activating virtual environment..."
+source venv/bin/activate
+
+# Install/upgrade dependencies
+echo "📦 Installing dependencies..."
+pip install --upgrade pip
+pip install -r requirements.txt
+
+# Run the build script
+echo "🔨 Starting build process..."
+python3 build.py
+
+echo "✅ Build script completed!"
\ No newline at end of file

main.py

+#!/usr/bin/env python3
+"""
+MbetterClient - Cross-platform multimedia client application
+Entry point for the application with command line argument handling
+"""
+
+import sys
+import os
+import argparse
+import signal
+import logging
+from pathlib import Path
+
+# Add the project root to Python path
+project_root = Path(__file__).parent
+sys.path.insert(0, str(project_root))
+
+from mbetterclient.core.application import MbetterClientApplication
+from mbetterclient.utils.logger import setup_logging
+from mbetterclient.config.settings import AppSettings
+
+def setup_signal_handlers(app):
+    """Setup signal handlers for graceful shutdown"""
+    def signal_handler(signum, frame):
+        logging.info(f"Received signal {signum}, initiating shutdown...")
+        if app:
+            app.shutdown()
+        sys.exit(0)
+    
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+    
+    # Windows doesn't have SIGHUP
+    if hasattr(signal, 'SIGHUP'):
+        signal.signal(signal.SIGHUP, signal_handler)
+
+def parse_arguments():
+    """Parse command line arguments"""
+    parser = argparse.ArgumentParser(
+        description='MbetterClient - Cross-platform multimedia client',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python main.py                    # Run in fullscreen mode
+  python main.py --no-fullscreen    # Run in windowed mode
+  python main.py --web-port 8080    # Custom web dashboard port
+  python main.py --debug            # Enable debug logging
+        """
+    )
+    
+    # Display options
+    parser.add_argument(
+        '--no-fullscreen',
+        action='store_true',
+        help='Run video player in windowed mode instead of fullscreen'
+    )
+    
+    parser.add_argument(
+        '--web-port',
+        type=int,
+        default=5001,
+        help='Port for web dashboard (default: 5001)'
+    )
+    
+    parser.add_argument(
+        '--web-host',
+        type=str,
+        default='127.0.0.1',
+        help='Host for web dashboard (default: 127.0.0.1)'
+    )
+    
+    # Database options
+    parser.add_argument(
+        '--db-path',
+        type=str,
+        default=None,
+        help='Custom database file path (default: data/mbetterclient.db)'
+    )
+    
+    # Logging options
+    parser.add_argument(
+        '--debug',
+        action='store_true',
+        help='Enable debug logging'
+    )
+    
+    parser.add_argument(
+        '--log-file',
+        type=str,
+        default=None,
+        help='Log file path (default: logs/mbetterclient.log)'
+    )
+    
+    # Development options
+    parser.add_argument(
+        '--dev-mode',
+        action='store_true',
+        help='Enable development mode with additional debugging'
+    )
+    
+    parser.add_argument(
+        '--no-qt',
+        action='store_true',
+        help='Disable PyQt interface (web dashboard only)'
+    )
+    
+    parser.add_argument(
+        '--no-web',
+        action='store_true',
+        help='Disable web dashboard (PyQt interface only)'
+    )
+    
+    parser.add_argument(
+        '--version',
+        action='version',
+        version='MbetterClient 1.0.0'
+    )
+    
+    return parser.parse_args()
+
+def validate_arguments(args):
+    """Validate command line arguments"""
+    if args.no_qt and args.no_web:
+        print("Error: Cannot disable both Qt and web interfaces")
+        sys.exit(1)
+    
+    if args.web_port < 1 or args.web_port > 65535:
+        print("Error: Web port must be between 1 and 65535")
+        sys.exit(1)
+    
+    # Create necessary directories
+    project_root = Path(__file__).parent
+    
+    # Data directory
+    data_dir = project_root / 'data'
+    data_dir.mkdir(exist_ok=True)
+    
+    # Logs directory
+    logs_dir = project_root / 'logs'
+    logs_dir.mkdir(exist_ok=True)
+    
+    # Assets directory
+    assets_dir = project_root / 'assets'
+    assets_dir.mkdir(exist_ok=True)
+    
+    # Templates directory
+    templates_dir = project_root / 'templates'
+    templates_dir.mkdir(exist_ok=True)
+
+def main():
+    """Main entry point"""
+    try:
+        # Parse command line arguments
+        args = parse_arguments()
+        
+        # Validate arguments and create directories
+        validate_arguments(args)
+        
+        # Setup logging
+        log_level = logging.DEBUG if args.debug else logging.INFO
+        log_file = args.log_file or 'logs/mbetterclient.log'
+        logger = setup_logging(level=log_level, log_file=log_file)
+        
+        logger.info("=" * 60)
+        logger.info("MbetterClient Starting")
+        logger.info("=" * 60)
+        logger.info(f"Arguments: {vars(args)}")
+        
+        # Create application settings
+        settings = AppSettings()
+        settings.fullscreen = not args.no_fullscreen
+        settings.web_host = args.web_host
+        settings.web_port = args.web_port
+        settings.debug_mode = args.debug or args.dev_mode
+        settings.enable_qt = not args.no_qt
+        settings.enable_web = not args.no_web
+        
+        if args.db_path:
+            settings.database_path = args.db_path
+        
+        # Create and initialize application
+        app = MbetterClientApplication(settings)
+        
+        # Setup signal handlers for graceful shutdown
+        setup_signal_handlers(app)
+        
+        # Initialize application
+        logger.info("Initializing application components...")
+        if not app.initialize():
+            logger.error("Failed to initialize application")
+            sys.exit(1)
+        
+        logger.info("Starting application...")
+        # Run the application (this blocks until shutdown)
+        exit_code = app.run()
+        
+        logger.info("Application finished")
+        sys.exit(exit_code)
+        
+    except KeyboardInterrupt:
+        print("\nInterrupted by user")
+        sys.exit(0)
+    except Exception as e:
+        print(f"Fatal error: {e}")
+        if args.debug if 'args' in locals() else False:
+            import traceback
+            traceback.print_exc()
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()
\ No newline at end of file

mbetterclient/__init__.py

+"""
+MbetterClient - Cross-platform multimedia client application
+
+A multi-threaded application with video playback, web dashboard, and REST API integration.
+"""
+
+__version__ = "1.0.0"
+__author__ = "MBetter Project"
+__email__ = "dev@mbetter.net"
+__description__ = "Cross-platform multimedia client with video overlay and web dashboard"
+
+from .core.application import MbetterClientApplication
+from .config.settings import AppSettings
+
+__all__ = [
+    'MbetterClientApplication',
+    'AppSettings',
+    '__version__',
+    '__author__',
+    '__email__',
+    '__description__'
+]
\ No newline at end of file

mbetterclient/api_client/__init__.py

+"""
+REST API Client for MbetterClient
+
+This module provides a threaded HTTP client for making configurable requests
+to external APIs with proper error handling and retry logic.
+"""
+
+from .client import APIClient
+
+__all__ = ['APIClient']
\ No newline at end of file

mbetterclient/core/__init__.py

+"""
+Core application components for MbetterClient
+"""
+
+from .application import MbetterClientApplication
+from .message_bus import MessageBus, Message, MessageType
+from .thread_manager import ThreadManager
+
+__all__ = [
+    'MbetterClientApplication',
+    'MessageBus',
+    'Message', 
+    'MessageType',
+    'ThreadManager'
+]
\ No newline at end of file

mbetterclient/database/__init__.py

+"""
+Database management for MbetterClient with SQLite and versioning support
+"""
+
+from .manager import DatabaseManager
+from .models import (
+    BaseModel,
+    DatabaseVersion,
+    UserModel,
+    ConfigurationModel,
+    ApiTokenModel,
+    LogEntryModel,
+    TemplateModel
+)
+from .migrations import DatabaseMigration, run_migrations
+
+__all__ = [
+    'DatabaseManager',
+    'BaseModel',
+    'DatabaseVersion', 
+    'UserModel',
+    'ConfigurationModel',
+    'ApiTokenModel',
+    'LogEntryModel',
+    'TemplateModel',
+    'DatabaseMigration',
+    'run_migrations'
+]
\ No newline at end of file

mbetterclient/qt_player/__init__.py

+"""
+PyQt video player with overlay templates for MbetterClient
+"""
+
+from .player import QtVideoPlayer
+from .overlay_engine import OverlayEngine, OverlayRenderer
+from .templates import TemplateManager, NewsTemplate
+
+__all__ = [
+    'QtVideoPlayer',
+    'OverlayEngine',
+    'OverlayRenderer', 
+    'TemplateManager',
+    'NewsTemplate'
+]
\ No newline at end of file

mbetterclient/utils/__init__.py

+"""
+Utility functions and classes for MbetterClient
+"""
+
+from .logger import setup_logging, get_logger
+from .helpers import ensure_directory, safe_filename, format_bytes, format_duration
+
+__all__ = [
+    'setup_logging',
+    'get_logger',
+    'ensure_directory',
+    'safe_filename', 
+    'format_bytes',
+    'format_duration'
+]
\ No newline at end of file

mbetterclient/web_dashboard/__init__.py

+"""
+Web dashboard for MbetterClient with authentication and configuration
+"""
+
+from .app import WebDashboard
+from .auth import AuthManager, jwt_required
+from .api import DashboardAPI
+
+__all__ = [
+    'WebDashboard',
+    'AuthManager',
+    'jwt_required',
+    'DashboardAPI'
+]
\ No newline at end of file