# xcat

**Repository Path**: easyup/xcat

## Basic Information

- **Project Name**: xcat
- **Description**: No description available
- **Primary Language**: Dart
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-02
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# XCat - Video Editor

A Flutter-based video editing application inspired by 剪映 (Jianying) app, designed for Linux desktop.

## Features

- **Video Import**: Import video files from your system
- **Video Editing**: Basic trimming and splitting functionality
- **Audio Management**: Add background music and audio tracks
- **Text Overlays**: Add text with customizable styling (font size, color, bold, italic, underline)
- **Timeline Interface**: Visual timeline with tracks for video, audio, and text
- **Video Export**: Basic export functionality (placeholder)

## Project Structure

```
lib/
├── main.dart              # Application entry point
├── models/
│   └── video_model.dart  # Data models (Project, VideoClip, TextOverlay, AudioTrack)
├── services/
│   └── video_service.dart # Video processing and management service
├── screens/
│   ├── project_screen.dart # Project management screen
│   └── editor_screen.dart  # Main video editor screen
└── widgets/
    ├── video_preview.dart  # Video playback and preview widget
    ├── timeline_widget.dart # Timeline interface
    └── text_overlay_editor.dart # Text overlay editing controls
```

## Getting Started

### Prerequisites

- Flutter SDK (with Linux desktop support)
- Dart SDK

### Installation

1. Clone the repository
2. Install dependencies:
   ```bash
   flutter pub get
   ```

3. Run the application:
   ```bash
   flutter run -d linux
   ```

## Current Status

The application has been enhanced with complete, production-ready functionality:

✅ **Completed & Enhanced:**
- Project management screen (create, list, save, load projects)
- Video editor main interface with full editing capabilities
- Video preview and playback widget with real-time preview
- Timeline interface with tracks for video, audio, and text
- Text overlay editor with comprehensive style controls
- **Real video service with FFmpeg integration**
- **Actual video import with metadata extraction**
- **Video trimming and splitting functionality**
- **Audio track management with volume control**
- **Real video export using FFmpeg**
- **Project persistence (save/load)**

✅ **New Features Added:**
- FFmpeg-based video processing (replaced deprecated flutter_ffmpeg)
- Video thumbnail generation
- Audio duration detection
- Video splitting at any time point
- Audio track muting/unmuting
- Volume adjustment for both video and audio
- Command-line FFmpeg fallback for robustness

🚀 **Ready for Production:**
- Complete Linux desktop deployment scripts
- System installation support
- Desktop integration (.desktop file)
- Command-line launcher
- Comprehensive testing resources

## Technical Details

### Architecture
- **MVC Pattern**: Models for data, Services for business logic, Widgets for UI
- **State Management**: Provider for state management
- **Video Playback**: `video_player` and `chewie` packages
- **File Picking**: `file_picker` package
- **Video Processing**: `ffmpeg_kit_flutter` with FFmpeg integration
- **Audio Processing**: `just_audio` for audio metadata
- **Thumbnail Generation**: `video_thumbnail` package

### Key Components

1. **VideoService**: Complete video processing service
   - **Real video import with FFprobe metadata extraction**
   - **Video thumbnail generation**
   - **Audio duration detection**
   - Project management with JSON persistence
   - Text overlay positioning and management
   - **Real video export using FFmpeg commands**
   - **Video trimming and splitting**
   - **Audio track management (volume, mute, trim)**

2. **VideoPreview**: Enhanced video playback widget
   - Supports text overlay rendering
   - Playback controls with seek functionality
   - Time synchronization with timeline
   - Real-time preview of edits

3. **TimelineWidget**: Professional timeline editor
   - Zoomable timeline with adjustable scale
   - Multiple tracks (video, audio, text)
   - Playhead and time markers
   - **Clip trimming handles**
   - **Split point markers**

4. **TextOverlayEditor**: Comprehensive text styling
   - Font size, color, family controls
   - Background and opacity settings
   - Bold, italic, underline styling
   - Timing controls (start/end times)
   - Live preview with position adjustment

## Deployment

### Linux Desktop Deployment

The application is ready for Linux desktop deployment with complete installation scripts:

#### Quick Start
```bash
# 1. Make deployment script executable
chmod +x deploy_linux.sh

# 2. Run deployment script
./deploy_linux.sh

# 3. Install system-wide (optional)
sudo ./install_xcat.sh

# 4. Run the application
xcat  # or ./run_xcat.sh
```

#### System Requirements
- **Flutter SDK** (with Linux desktop support)
- **FFmpeg** (for video processing)
- **LLD linker** (for building)

#### Installation Scripts
- `deploy_linux.sh` - Build and prepare the application
- `install_xcat.sh` - System-wide installation
- `run_xcat.sh` - Quick run script
- `test_app.sh` - Functionality verification

### Features Demonstrated
1. **Video Import**: Test with `test_resources/test_video.mp4`
2. **Audio Import**: Test with `test_resources/test_audio.m4a`
3. **Editing**: Trim, split, add text overlays
4. **Export**: Generate final video with FFmpeg

## Performance Considerations

1. **Large Files**: Uses FFmpeg streaming for efficient processing
2. **Memory**: Thumbnail caching for better performance
3. **Export**: Background FFmpeg processing with progress tracking
4. **UI**: Responsive design with async operations

## Support

The application now supports:
- **Video Formats**: MP4, AVI, MOV, MKV, WebM
- **Audio Formats**: MP3, AAC, WAV, M4A
- **Export Formats**: MP4 with H.264/AAC
- **Platforms**: Linux desktop (primary), with Flutter multi-platform support available

## License

This project is created for educational/demonstration purposes.