Imported from RFV56/BinaryPlayer (AGENTS.md). Install upstream with npx skills add RFV56/BinaryPlayer. Copyright stays with the author.

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project Overview

BinaryPlayer is a Qt6-based video player that supports playing and converting .bin format video files. The application uses OpenCV for video processing and provides a GUI with video controls, playlist management, and export functionality.

Key Architecture Components

• Main Application: MainWindow class manages the GUI, video playback controls, and user interactions
• Video Processing: bin2mat class handles reading binary video files and converting frames to OpenCV Mat format
• Image Processing: debayer class handles image demosaicing for raw sensor data
• Background Processing: VideoConverter worker class handles video to AVI conversion in separate threads
• UI: Qt Designer interface defined in mainwindow.ui

Core Dependencies

• Qt6 (Widgets, Core, Gui modules)
• OpenCV 4.x (configured for MinGW on Windows, Homebrew on macOS)
• CMake build system

Build Commands

Windows (MinGW)

# Quick build using provided script (推荐)
build-and-deploy.bat

# 仅构建，不打包
build-and-deploy.bat --build-only

# 仅部署已构建的项目
build-and-deploy.bat --deploy-only

# 仅创建安装包
build-and-deploy.bat --installer

macOS

# 使用自动化脚本 (推荐)
./build-and-deploy.sh

# 仅构建
./build-and-deploy.sh --build-only

# 仅部署
./build-and-deploy.sh --deploy-only

# 创建DMG安装包
./build-and-deploy.sh --dmg

Automated Build & Deploy Script

Quick Start (Recommended)

For macOS, use the comprehensive build-and-deploy.sh script that handles the entire build and deployment process:

# Make script executable
chmod +x build-and-deploy.sh

# Complete build and deployment (default)
./build-and-deploy.sh

# Or use specific options:
./build-and-deploy.sh --build-only    # Only build, don't package
./build-and-deploy.sh --deploy-only   # Only package (requires build)
./build-and-deploy.sh --dmg           # Create professional DMG installer
./build-and-deploy.sh --help          # Show help information

The script automatically:

• ✅ Checks dependencies (CMake, Qt6, OpenCV)
• ✅ Configures and builds the project
• ✅ Creates .app bundle with embedded dependencies
• ✅ Generates professional DMG with Applications symlink
• ✅ Includes installation instructions in Chinese
• ✅ Sets up proper code signing and security attributes
• ✅ Supports both Intel and Apple Silicon Macs

Output: Creates deploy-macos/BinaryPlayer_1.3.0.dmg (78MB) ready for distribution

Manual DMG Creation

If you prefer to create the DMG manually or need to customize the layout, follow these steps:

Step 1: Create DMG Contents Structure

# Create temporary directory
mkdir -p deploy-macos/temp_dmg
cd deploy-macos/temp_dmg

# Copy the app bundle
cp -R ../BinaryPlayer.app .

# Create Applications alias (IMPORTANT: This enables drag-to-install)
ln -s /Applications "Applications"

# Create installation instructions
cat > "Install BinaryPlayer.txt" << 'EOF'
[Installation instructions here - see template above]
EOF

Step 2: Create DMG with hdiutil

# Method 1: Direct DMG creation (simple)
hdiutil create -srcfolder temp_dmg \
  -volname "BinaryPlayer v1.3.0" \
  -fs HFS+ \
  -format UDZO \
  -size 500m \
  BinaryPlayer_1.3.0.dmg

# Method 2: Using sparse image for better layout control
hdiutil create -size 500m -fs HFS+ -volname "BinaryPlayer v1.3.0" "BinaryPlayer_1.3.0.dmg.sparseimage"
hdiutil attach "BinaryPlayer_1.3.0.dmg.sparseimage"
cp -R temp_dmg/* "/Volumes/BinaryPlayer v1.3.0/"
hdiutil detach "/Volumes/BinaryPlayer v1.3.0"
hdiutil convert "BinaryPlayer_1.3.0.dmg.sparseimage" -format UDZO -o "BinaryPlayer_1.3.0.dmg"
rm "BinaryPlayer_1.3.0.dmg.sparseimage"

Step 3: Customize DMG Layout (Optional)

Create an AppleScript to set up a professional-looking DMG window:

# Create setup script
cat > setup_dmg_layout.scpt << 'EOF'
tell application "Finder"
    tell disk "BinaryPlayer v1.3.0"
        open
        set current view of container window to icon view
        set toolbar visible of container window to false
        set statusbar visible of container window to false
        set the bounds of container window to {400, 100, 920, 500}
        set viewOptions to the icon view options of container window
        set arrangement of viewOptions to not arranged
        set icon size of viewOptions to 100
        make new alias file at container window to POSIX file "/Applications" with properties {name:"Applications"}
        set position of item "BinaryPlayer.app" of container window to {100, 150}
        set position of item "Applications" of container window to {300, 150}
        set position of item "Install BinaryPlayer.txt" of container window to {200, 350}
        close
        open
        update without registering applications
    end tell
end tell
EOF

# Run the script (requires Finder access)
osascript setup_dmg_layout.scpt

Important Notes:

• ✅ Applications alias: Must use ln -s /Applications "Applications" (not mkdir!)
• ✅ Text encoding: Ensure Install BinaryPlayer.txt uses UTF-8 encoding
• ✅ DMG location: All DMG files are stored in deploy-macos/ directory
• ✅ File naming: DMG files follow pattern BinaryPlayer_X.Y.Z.dmg
• ✅ Testing: Always test DMG by mounting it and verifying drag-to-install works

Deployment

Windows Deployment

# Deploy application with dependencies
deploy-mingw.bat

# Create installer (requires NSIS)
makensis installer-mingw.nsi

macOS Deployment

# After build
make install
macdeployqt BinaryPlayer.app

Key File Structure

• main.cpp - Application entry point
• mainwindow.* - Main GUI window and application logic
• bin2mat.* - Binary file reader for video frames
• debayer.* - Image demosaicing algorithms
• mainwindow.ui - Qt Designer UI layout
• CMakeLists.txt - Build configuration
• config.h.in - Version configuration template

Development Notes

OpenCV Configuration

The build system automatically detects MinGW vs MSVC and configures OpenCV paths accordingly:

• MinGW: D:/LIB/OpenCV4.5.2_MinGW
• MSVC: C:/opencv/build or D:/LIB/OpenCV4.5.2_VS
• macOS: /usr/local/lib/cmake/opencv4 (Homebrew)

Thread Safety

Video conversion uses background threading with QThread and VideoConverter worker to prevent UI blocking.

Settings Persistence

Application settings (last played video, position, preferences) are managed using QSettings.

Keyboard Shortcuts

• A/←: Previous frame
• D/→: Next frame
• S: Export current frame
• Space: Play/Pause

Testing

No automated test suite is currently configured. Testing should be done manually by:

1. Loading various .bin video files
2. Testing playback controls and frame navigation
3. Verifying export functionality (both single frames and AVI conversion)
4. Testing keyboard shortcuts
5. Verifying settings persistence across restarts