Leak_Technologies/VideoTools
Leak_Technologies/VideoTools
2
1
Fork 1
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity
a82e7f8308
VideoTools/scripts/git_converter/ai-speak.md

12 KiB
Raw Blame History

🤖 AI-Speak: Development Collaboration Guide

🎯 PURPOSE: This file serves as the central collaboration hub between Stu's AI and development team for the lt-convert.sh cross-platform video converter project.

👥 Partners:

  • Stu's AI Assistant (development partner)
  • Stu (human developer & tester)
  • Jake (human developer)
  • User (Windows testing & feedback)

Role focus: Jake leads the git_converter scripts (lt-convert modules); Stu is driving the overall VideoTools GUI and app stack.

📅 Project: lt-convert.sh - Cross-platform Video Converter
🔄 Last Updated: 2025-12-14

🧭 Project Overview (VideoTools & lt-convert)

  • VideoTools is a full FFmpeg-based conversion suite with a professional GUI; DVD-compliant output is one focus area (MPEG-2 NTSC/PAL, AC-3, DVDStyler/PS2), but the scope includes broad AV1/HEVC/H.264 workflows, queueing, and future modules (merge/trim/filters/etc.).
  • Core app: Go-based modular architecture (convert/queue/ui/player), batch queue with pause/resume/history, smart framerate/audio conversion, aspect handling, and validation.
  • Scripts: lt-convert.sh provides cross-platform hardware-accelerated AV1/HEVC conversions with modular bash components (hardware/codec/quality/filters/encode).
  • Key docs: README.md (overview), INSTALLATION.md, DVD_USER_GUIDE.md, DVD_IMPLEMENTATION_SUMMARY.md, QUEUE_SYSTEM_GUIDE.md, INTEGRATION_GUIDE.md, BUILD_AND_RUN.md.
  • Current Linux display focus is Wayland-first while retaining X11 support; VT_Player is moving to GTK and not yet functional.

📜 Release/Planning Snapshot

  • dev11–dev13: See DONE.md (batch queue, multi-video nav, auto crop/fps UI, encoder presets, target size mode, compare module, hardware detection, mobile profiles, 10-bit defaults, deinterlace, etc.).
  • dev14: Windows compatibility (cross-compilation, path/process handling, GPU detection, docs) completed; installer planned for dev15 per TODO.md.
  • dev15 (planned in TODO.md): UI polish (progress indicators), performance optimizations, merge/trim/filters module implementations, encoding enhancements (2-pass, custom args, presets), Blu-ray groundwork, Windows installer.
  • dev16/dev17: Not documented in repo—need Jake to outline what shipped; flag to capture in DONE.md.
  • dev18 (needs plan): Define next wave after dev15–17 catch-up; likely focus on stabilization, installer completion, progress bars/batch polish, subtitle support, GTK player viability, Blu-ray, and advanced modules—require Jake’s input.

🧩 lt-convert Presets to Port into VT

  • Quality presets (simple + advanced UIs): CRF 18 (AV1/HEVC), CRF 16 (near-lossless), CRF 20 (balanced), Source/no-change, and Custom bitrate.
  • Resolution/scaling: Source, 720p/1080p/1440p/4K, 2x/4x with scaler choice (bicubic/lanczos/bilinear); surface common picks in the simple menu.
  • FPS: Original or 60 fps toggle.
  • Color looks (slot into Filters/Upcale pipeline): pink-skin fix, warm, cool, DVD restore, 90s restore, VHS restore, anime preservation; keep an off option. Consider pairing DVD/Anime looks with upscale flows.
  • Containers/codecs: MKV/MP4 with AV1/HEVC; map hardware variants (NVENC/AMF/QSV) when available.
  • Presets are WIP but promising—integrate quality/resolution/fps now; fold color presets into the Filters module once it lands.

📖 HOW TO USE THIS FILE (For Stu's AI)

🔍 READING THIS FILE:

  1. Start at the top - understand project context
  2. Check Current Status - see what's completed vs pending
  3. Review Priority Tasks - focus on high-priority items first
  4. Read Conversation Log - understand past issues and solutions
  5. Check Testing Status - see what needs validation

✏️ UPDATING THIS FILE:

  1. IMMEDIATELY UPDATE when making any changes or suggestions
  2. USE CLEAR MARKERS like [x] for completed, [ ] for pending
  3. ADD TO CONVERSATION LOG with date and issue description
  4. UPDATE TESTING CHECKLISTS for new features
  5. PROPOSE IMPROVEMENTS in the suggested improvements section

🎯 YOUR ROLE:

  • Cross-platform guardian - ensure Windows/Linux compatibility
  • Proactive improver - suggest optimizations and new features
  • Documentation keeper - maintain clear development history
  • Testing coordinator - track what needs to be validated

📋 Current Development Status

📋 Current Development Status

✅ Completed Features

  • Modular architecture implementation
  • Cross-platform compatibility (Windows/Linux/macOS)
  • GPU/Encoder selection with auto-detection
  • Codec selection (AV1/HEVC)
  • Container selection (MKV/MP4)
  • Quality modes (Source/CRF/Custom bitrate)
  • Color correction presets (8 options)
  • Drag-and-drop functionality
  • Hardware benchmarking
  • Error handling and validation

🔄 Current Issues Being Addressed

  • None currently - all major features implemented

🎯 Priority Tasks

🚨 High Priority

  • Test on actual Wayland Linux system (primary target) while keeping X11 support
  • Verify drag-and-drop works across different desktop environments
  • Performance testing with various video formats
  • Add progress bars for long conversions
  • Implement batch queue processing

📈 Medium Priority

  • Add subtitle support (burn-in/soft-subs) once core modules stabilize
  • Create comprehensive test suite

🔮 Future Enhancements

  • GPU memory usage optimization
  • Multi-threaded processing for multiple files
  • Audio-only/video-only modes
  • Preset system for common configurations
  • Integration with video metadata databases

💡 SUGGESTED IMPROVEMENTS FOR STU TO CONSIDER:

  • Progress bars using pv or custom progress indicators
  • Batch queue system for processing multiple files sequentially
  • Configuration file support for saving user preferences
  • Logging system with timestamps and error details
  • Automatic backup of original files before conversion
  • Smart file naming with metadata integration
  • Parallel processing for multi-core CPU encoding
  • GPU memory monitoring and automatic adjustment
  • Resume capability for interrupted conversions
  • Integration with system notifications for completion alerts

💬 Conversation Log

2025-12-14 - Line endings + sync

Stu's AI: Added .gitattributes to enforce LF endings for all shell scripts, preventing Windows CRLF issues. Pulled/merged Jake's latest lt-convert.sh changes and set the script executable bit. Repo is clean and up to date on master.

2025-12-14 - Initial Cross-Platform Fixes

Stu's AI: "My friend Stu uses Wayland Linux and he said that drag and drop function onto 'lt-convert.sh' did not work for him. He said that it also did not detect video files within his current folder."

Response: Implemented comprehensive cross-platform fixes:

  • Fixed file detection using explicit scanning instead of nullglob
  • Added lshw hardware detection for Linux
  • Implemented cross-platform timeout handling
  • Improved path resolution for different shells
  • Added more video format support

Status: ✅ RESOLVED - Awaiting testing feedback from Stu

🧪 Testing Checklist

Windows Testing

  • Git Bash compatibility
  • WSL compatibility
  • PowerShell compatibility
  • Drag-and-drop from File Explorer

Linux Testing

  • Wayland drag-and-drop (GNOME/KDE) ← STU TO TEST
  • X11 drag-and-drop
  • Terminal execution
  • Hardware detection (NVIDIA/AMD/Intel)
  • File permissions handling

🧪 LIVE TESTING - Current Changes

Feature: Cross-platform drag-and-drop and file detection Status: ⏳ AWAITING TEST RESULTS Testers:

  • User: Windows ✅ (confirmed working)
  • Stu: Linux Wayland 🔄 PENDING (after pulling latest .gitattributes + executable bit)

Expected Results:

  • Drag files onto script → Should process them
  • Double-click script → Should find video files in directory
  • Hardware detection → Should detect GPU/encoders
  • All menus → Should display properly

📝 Development Notes

Known Limitations

  • Windows timeout fallback uses manual process killing
  • Some Wayland desktop environments may have different drag-and-drop behavior
  • Hardware detection varies by Linux distribution
  • Wayland is the primary Linux target; X11 support must be preserved
  • VT_Player is moving to GTK; current GTK player support is not yet functional

Testing Needs

  • Wayland drag/drop and file detection (Linux primary), X11 parity
  • Batch queue reliability and performance under load; progress indicators once implemented
  • Windows installer (planned for dev15), GPU detection/encoder selection on NVIDIA/AMD/Intel
  • Cross-platform hardware benchmarking and encoder fallback paths
  • Subtitle flow (once added) and Blu-ray pipeline (planned dev15+)

Technical Debt

  • Consider replacing bash arrays for better portability
  • Evaluate using Python for complex GUI interactions
  • Standardize error message formatting

🔄 Next Steps

  1. Immediate: Get feedback from Stu on Wayland testing
  2. Short-term: Address any compatibility issues found; add progress bars and batch queue processing
  3. Medium-term: Build comprehensive test suite; plan subtitle support once core is stable
  4. Long-term: Consider GUI frontend development

📞 Contact & Collaboration

For Stu's AI: When working on this project, please:

Workflow Rules

  • Commit after every meaningful change; keep commits small and descriptive.
  • Update TODO.md and DONE.md to reflect new work, completed tasks, and testing results.
  • Keep this ai-speak.md in sync with priorities, logs, and testing status.

🔄 When Changes Are Made:

  1. IMMEDIATELY UPDATE this file with any suggestions or changes
  2. Mark completed tasks with [x]
  3. Add new tasks to appropriate priority section
  4. Update conversation log with user feedback

💡 PROACTIVE IMPROVEMENTS:

  1. REGULARLY SUGGEST improvements and optimizations to Stu
  2. IDENTIFY OPPORTUNITIES for:
    • Performance enhancements
    • User experience improvements
    • Code quality and maintainability
    • New feature ideas
  3. PROPOSE SPECIFIC SOLUTIONS with code examples when possible
  4. RESEARCH BEST PRACTICES for video conversion and shell scripting

🔍 Cross-Platform Compatibility Review:

  1. ALWAYS CHECK for compatibility issues across:
    • Windows (Git Bash, WSL, PowerShell)
    • Linux (Wayland, X11, various distros)
  2. IDENTIFY POTENTIAL BREAKING CHANGES before implementation
  3. SUGGEST ALTERNATIVES if a feature won't work cross-platform

📋 Documentation Requirements:

  1. UPDATE TESTING CHECKLISTS for new features
  2. ADD TECHNICAL NOTES for any platform-specific workarounds
  3. VERIFY all module dependencies are cross-platform (Windows/Linux only)

⚠️ CRITICAL:

  • NEVER IMPLEMENT a feature without cross-platform consideration
  • ALWAYS NOTIFY in this file when platform-specific code is added
  • COORDINATE TESTING with Stu and user feedback before marking complete

Goal: Create the most robust, cross-platform video converter available.

🚨 Compatibility Alert System

Recent Changes Requiring Review:

  • None currently - all changes cross-platform verified

Platform-Specific Code Sections:

  • Windows: wmic hardware detection, timeout fallback
  • Linux: lspci/lshw hardware detection, timeout command