{"id":49443216,"url":"https://github.com/roymejia2217/vcompress","last_synced_at":"2026-04-29T21:05:27.065Z","repository":{"id":322907872,"uuid":"1087526494","full_name":"roymejia2217/VCompress","owner":"roymejia2217","description":"Intelligent Android video compression app with hardware acceleration, batch processing, and Material Design 3 UI. Built with Flutter, FFmpeg, and Riverpod.","archived":false,"fork":false,"pushed_at":"2026-02-01T00:07:12.000Z","size":38244,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-01T10:56:54.778Z","etag":null,"topics":["android","dart","ffmpeg","flutter","hardware-acceleration","open-source","riverpod","video-compression","video-compressor","video-processing"],"latest_commit_sha":null,"homepage":"https://roymejia2217.github.io/VCompress/","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roymejia2217.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-01T04:57:17.000Z","updated_at":"2026-01-31T23:56:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/roymejia2217/VCompress","commit_stats":null,"previous_names":["roymejia2217/vcompress"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/roymejia2217/VCompress","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roymejia2217%2FVCompress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roymejia2217%2FVCompress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roymejia2217%2FVCompress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roymejia2217%2FVCompress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roymejia2217","download_url":"https://codeload.github.com/roymejia2217/VCompress/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roymejia2217%2FVCompress/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32443596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T20:22:27.477Z","status":"ssl_error","status_checked_at":"2026-04-29T20:22:26.507Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","dart","ffmpeg","flutter","hardware-acceleration","open-source","riverpod","video-compression","video-compressor","video-processing"],"created_at":"2026-04-29T21:05:22.731Z","updated_at":"2026-04-29T21:05:27.058Z","avatar_url":"https://github.com/roymejia2217.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"android/app/src/main/play_store_512.png\" alt=\"VCompressor Logo\" width=\"200\" height=\"200\"\u003e\n\u003c/div\u003e\n\n# VCompress\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Flutter](https://img.shields.io/badge/Flutter-3.32.8-blue.svg)](https://flutter.dev)\n[![Dart](https://img.shields.io/badge/Dart-3.8.1-blue.svg)](https://dart.dev)\n[![Android](https://img.shields.io/badge/Android-7.0%2B-green.svg)](https://www.android.com)\n[![GitHub Release](https://img.shields.io/github/v/release/roymejia2217/VCompress.svg)](https://github.com/roymejia2217/VCompress/releases)\n[![GitHub last commit](https://img.shields.io/github/last-commit/roymejia2217/VCompress.svg)](https://github.com/roymejia2217/VCompress)\n\nA powerful Android video compression application built with Flutter. VCompress provides intelligent video optimization with hardware acceleration, batch processing, and real-time progress tracking.\n\n**Platforms**: Android (7.0+) | **Languages**: [English](README.md) | [Español](README_ES.md) | [Français](README_FR.md) | [Italiano](README_IT.md)\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [User Interface Preview](#user-interface-preview)\n- [Technical Specifications](#technical-specifications)\n- [Architecture](#architecture)\n- [Installation \u0026 Setup](#installation--setup)\n- [Usage](#usage)\n- [Development](#development)\n- [Testing](#testing)\n- [Performance Optimizations](#performance-optimizations)\n- [Compatibility](#compatibility)\n- [Troubleshooting](#troubleshooting)\n- [Dependency Management](#dependency-management)\n- [Architecture Decisions](#architecture-decisions)\n- [Contributing](#contributing)\n- [FAQ](#faq)\n- [License](#license)\n- [Support](#support)\n\n---\n\n## Features\n\n### Core Compression\n- **Multiple Compression Algorithms**: VP8, VP9, H.264, H.265 with hardware acceleration support\n- **Batch Processing**: Compress multiple videos simultaneously with intelligent queueing\n- **Real-time Progress Tracking**: Live progress indicators for import and compression operations\n- **Smart Resolution Selection**: Predefined profiles (720p, 1080p, 2K, 4K) with custom options\n- **Format Flexibility**: Support for MP4, WebM, MKV output containers\n\n### Advanced Features\n- **Hardware Detection**: Automatic detection of device capabilities (CPU cores, RAM, codec support)\n- **FFmpeg Integration**: Industry-standard video processing with ffmpeg_kit_flutter_new\n- **Thumbnail Generation**: Automatic video thumbnail extraction with caching\n- **Metadata Extraction**: Complete video analysis (duration, resolution, codec, fps)\n- **File Management**: Safe file replacement with backup options, MediaStore URI resolution\n- **Notification System**: Real-time compression progress notifications\n\n### User Experience\n- **Material Design 3**: Modern, responsive UI with dynamic color theming\n- **Multi-language Support**: Spanish (es), English (en), French (fr) with Flutter Intl\n- **Localized Settings**: Theme mode (light/dark/system), language selection, custom save directory\n- **Dark Mode**: Full Material 3 dark theme support with Flex Color Scheme\n- **Accessibility**: Semantic labels, keyboard navigation, screen reader support\n\n---\n\n## User Interface Preview\n\n### Compression Workflow\n\nVCompress features an intuitive Material Design 3 interface that guides users through the video compression process:\n\n| **Step 1: Import** | **Step 2: Configure** | **Step 3: Process** | **Step 4: Results** |\n|:---:|:---:|:---:|:---:|\n| Browse and select videos from your device | Configure compression settings (algorithm, resolution, format) | Monitor real-time compression progress | View compressed videos and export |\n| ![Home](docs/mockups/home_page_withvideo.png) | ![Config Modal](docs/mockups/videoconfigmodal.png) | ![Compressing](docs/mockups/process_page_video_compressing.png) | ![Results](docs/mockups/process_Page_result_videocompressed.png) |\n\n### Advanced Features\n\n**Fine-tuned Settings** - Expand configuration modal for granular control over compression parameters\n![Expanded Modal](docs/mockups/videoconfigmodal_expanded.png)\n\n**Native Playback** - Preview compressed videos using your device's native media player\n![Playback](docs/mockups/video_player_watching_result.png)\n\n---\n\n## Technical Specifications\n\n### System Requirements\n\n| Component | Minimum | Recommended |\n|-----------|---------|-------------|\n| **Android** | 7.0 (API 24) | 12.0+ (API 31+) |\n| **Dart** | 3.6.0 | 3.8.1 |\n| **Flutter** | 3.19.0 | 3.32.8 |\n| **RAM** | 2GB | 4GB+ |\n| **Storage** | 150MB free | 500MB+ free |\n\n### Supported Codecs\n\n**Video Codecs**: VP8, VP9, H.264, H.265, AV1 (hardware-dependent)  \n**Audio Codecs**: AAC, Opus, Vorbis  \n**Containers**: MP4, WebM, MKV  \n**Pixel Formats**: Yuv420, Yuv422, Yuv444  \n\n### Hardware Acceleration\n\n| Codec | Support |\n|-------|---------|\n| **H.264** | MediaCodec (hardware) |\n| **H.265** | MediaCodec (hardware) |\n| **VP9** | MediaCodec (hardware on 8.0+) |\n\n---\n\n## Architecture\n\n### Technology Stack\n\n```\nState Management:    Riverpod 2.6.1 (FutureProvider, StateNotifier)\nNavigation:         GoRouter 16.2.0 (type-safe routing)\nUI Framework:       Flutter Material 3\nVideo Processing:   FFmpeg (ffmpeg_kit_flutter_new 4.1.0)\nStorage:            SharedPreferences + Path Provider\nIcons:              Phosphor Flutter 2.1.0\nTheming:            Flex Color Scheme 8.3.1\nLocalization:       Flutter Intl (.arb files)\nPermissions:        Permission Handler 12.0.1\nFile Picking:       File Picker 10.3.3\nThumbnails:         Video Thumbnail 0.5.6\n```\n\n### Project Structure\n\n```\nlib/\n├── core/                              # Core architecture \u0026 utilities\n│   ├── accessibility/                # Accessibility helpers\n│   ├── constants/                    # Constants, design tokens, animations\n│   ├── error/                        # Error handling \u0026 definitions\n│   ├── extensions/                   # Dart extensions\n│   ├── hardware/                     # Hardware detection logic\n│   ├── logging/                      # Logging utilities\n│   ├── performance/                  # Memory management\n│   ├── result/                       # Result type pattern\n│   ├── services/                     # Core services\n│   └── validation/                   # Validation logic\n│\n├── data/                              # Data layer implementation\n│   ├── repositories/                 # Repository implementations\n│   └── services/                     # Data services (FFmpeg, MediaStore, etc.)\n│\n├── domain/                            # Domain layer (Business Logic)\n│   ├── models/                       # Domain models\n│   ├── repositories/                 # Repository interfaces\n│   └── usecases/                     # Application use cases\n│\n├── l10n/                              # Localization files (.arb)\n│\n├── models/                            # Shared data models\n│\n├── providers/                         # State management (Riverpod)\n│\n├── router/                            # Navigation configuration\n│\n├── services/                          # Global services (Permissions)\n│\n├── ui/                                # User Interface (Widgets \u0026 Pages)\n│   ├── home/                         # Home screen\n│   ├── process/                      # Processing screen\n│   ├── settings/                     # Settings screen\n│   ├── theme/                        # Theme configuration\n│   └── widgets/                      # Reusable widgets\n│\n├── utils/                             # General utilities\n│\n└── main.dart                          # Application entry point\n\nandroid/                               # Android-specific configuration\n├── app/src/main/\n│   ├── AndroidManifest.xml           # Android manifest\n│   ├── java/                         # Java source code\n│   ├── kotlin/                       # Kotlin source code\n│   └── res/\n│       ├── mipmap-*/                 # App icons (mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi)\n│       ├── values/                   # Strings, colors, themes\n│       └── play_store_512.png        # Play Store icon\n│\n├── build.gradle                      # Project-level Gradle\n└── settings.gradle                   # Gradle settings\n\ntest/                                  # Test suite (5 categories)\n├── accessibility/                    # Accessibility tests\n├── integration/                      # End-to-end tests\n├── performance/                      # Performance benchmarks\n├── unit/                             # Unit tests\n└── widget/                           # Widget tests\n```\n\n## Installation \u0026 Setup\n\n### Prerequisites\n- **Flutter**: 3.19.0+ ([install guide](https://flutter.dev/docs/get-started/install))\n- **Dart**: 3.6.0+ (bundled with Flutter)\n- **Android SDK**: API 24+ for Android builds\n\n### Clone Repository\n```bash\ngit clone https://github.com/roymejia2217/VCompress.git\ncd VCompressor\n```\n\n### Install Dependencies\n```bash\nflutter pub get\n```\n\n### Generate Localization Files\n```bash\nflutter gen-l10n\n```\n\n### Run Application\n\n**Android Device/Emulator**:\n```bash\nflutter run -d android\n# or for specific device\nflutter run -d \u003cdevice_id\u003e\n```\n\n**Release Build (Android)**:\n```bash\nflutter build apk --release\n# or app bundle for Play Store\nflutter build appbundle --release\n```\n\n---\n\n## Usage\n\n### Basic Workflow\n\n1. **Import Videos**: Tap the import button, select one or multiple videos\n2. **Configure Compression**: Choose algorithm, resolution, format (individual or batch)\n3. **Monitor Progress**: Watch real-time progress bars during import and compression\n4. **Save Compressed Videos**: Files save to configured directory (default: Downloads/VCompress)\n\n### Compression Settings\n\n| Setting | Options | Notes |\n|---------|---------|-------|\n| **Algorithm** | VP8, VP9, H.264, H.265, AV1 | H.265 best compression, H.264 best compatibility |\n| **Resolution** | 720p, 1080p, 2K, 4K, Custom | Downscaling reduces file size significantly |\n| **Format** | MP4, WebM, MKV | MP4 most compatible, WebM smallest |\n| **Quality** | 18-28 CRF | Lower = better quality, larger files |\n| **FPS** | Original, 15, 24, 30, 60 | Reducing fps saves bandwidth |\n\n### Batch Processing\n\nEnable batch mode to compress multiple videos with consistent settings:\n1. Select multiple videos during import\n2. Configure settings once (applied to all)\n3. Queue processes automatically\n4. Monitor all progress in single list\n\n### Storage Configuration\n\nChange save directory in Settings \u003e Storage \u003e Change Folder. Custom locations supported on Android 11+.\n\n---\n\n## Development\n\n### Code Style\n\n- **Format**: Run `flutter format lib/` regularly\n- **Analysis**: Keep `flutter analyze` warnings at 0\n- **Comments**: Explain *why*, not *what* (code shows what)\n\n### Common Workflows\n\n**Bug Fix Workflow**:\n```bash\n# 1. Identify issue\nflutter analyze\n\n# 2. Locate relevant files\ngrep -r \"search_term\" lib/\n\n# 3. Fix code\n# (edit files)\n\n# 4. Format and analyze\nflutter format lib/\nflutter analyze\n\n# 5. Test fix\nflutter test\nflutter run -d android\n```\n\n**Feature Implementation**:\n```bash\n# 1. Create/modify files\n# (edit files)\n\n# 2. Format code\nflutter format lib/\n\n# 3. Analyze for issues\nflutter analyze\n\n# 4. Run tests\nflutter test test/unit/  # or specific test file\n\n# 5. Test in app\nflutter run -d android\n```\n\n### State Management with Riverpod\n\n**FutureProvider** (async data, read-only):\n```dart\nfinal videoMetadataProvider = FutureProvider.family((ref, String path) async {\n  return await ref.watch(videoMetadataServiceProvider).extractMetadata(path);\n});\n```\n\n**StateNotifierProvider** (mutable state):\n```dart\nfinal videoConfigProvider = StateNotifierProvider.family((ref, VideoTask task) {\n  return VideoConfigNotifier(task);\n});\n```\n\n**Watching providers**:\n```dart\nfinal metadata = ref.watch(videoMetadataProvider(videoPath));\nmetadata.when(\n  data: (data) =\u003e Text('Duration: ${data.duration}'),\n  loading: () =\u003e CircularProgressIndicator(),\n  error: (err, st) =\u003e Text('Error: $err'),\n);\n```\n\n---\n\n## Testing\n\n### Test Categories\n\n| Category | Location | Purpose |\n|----------|----------|---------|\n| **Unit** | `test/unit/` | Service logic, algorithms, calculations |\n| **Widget** | `test/widget/` | UI components, rendering, interactions |\n| **Integration** | `test/integration/` | End-to-end flows, multiple services |\n| **Accessibility** | `test/accessibility/` | Screen readers, keyboard navigation |\n| **Performance** | `test/performance/` | Benchmarks, memory usage, frame rates |\n\n### Run Tests\n\n```bash\n# All tests\nflutter test\n\n# Specific category\nflutter test test/unit/\n\n# Specific test file\nflutter test test/unit/services/video_processor_service_test.dart\n\n# With coverage\nflutter test --coverage\n```\n\n### Example Unit Test\n\n```dart\nvoid main() {\n  group('VideoSettings', () {\n    test('defaults should be valid', () {\n      final settings = VideoSettings.defaults();\n      expect(settings.preset, CompressionAlgorithm.h265);\n      expect(settings.resolution, VideoResolution.hd1080);\n    });\n\n    test('quality should be in valid range', () {\n      final settings = VideoSettings(quality: 18);\n      expect(settings.quality, inInclusiveRange(18, 28));\n    });\n  });\n}\n```\n\n---\n\n## Performance Optimizations\n\n### Memory Management\n\n- **Thumbnail Caching**: Disk cache for video thumbnails (CacheService)\n- **Lazy Loading**: Lists use `ListView.builder` for efficient memory\n- **Memory Monitoring**: `MemoryManager` tracks heap usage, triggers cleanup\n- **Metadata Caching**: Extract once, reuse across operations\n\n### FFmpeg Optimization\n\n- **Hardware Acceleration**: Uses MediaCodec on Android for H.264/H.265\n- **Profile-Guided Encoding**: FFmpeg preset (ultrafast, superfast, fast) based on device\n- **Chunk Processing**: Processes video in segments for large files\n- **Parallel Tasks**: Multiple compressions with intelligent queueing\n\n### UI Performance\n\n- **Provider Selectors**: Watch only needed state (`.select()`)\n- **Repaint Boundaries**: Progress bars don't rebuild entire list\n- **Const Constructors**: Widgets marked `const` where possible\n- **Image Caching**: Thumbnails cached with ImageCache\n\n### Network \u0026 Storage\n\n- **Local Processing**: All video processing happens on-device\n- **Efficient I/O**: SharedPreferences for settings, Path Provider for files\n- **MediaStore Integration**: Uses Android MediaStore for proper URI resolution\n\n---\n\n## Compatibility\n\n### Android Versions\n\n| Version | API | Status | Notes |\n|---------|-----|--------|-------|\n| **7.0** | 24 | Supported | Minimum version |\n| **8.0** | 26 | Supported | VP9 hardware support |\n| **9.0** | 28 | Supported | Improved scoped storage |\n| **11.0+** | 30+ | Recommended | Full scoped storage |\n| **14.0+** | 34+ | Full support | Latest APIs |\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n#### Build Fails: \"Android SDK not found\"\n```bash\n# Ensure Flutter can find Android SDK\nflutter config --android-sdk /path/to/android-sdk\n\n# Run diagnostics\nflutter doctor\n```\n\n#### FFmpeg Errors During Compression\n```bash\n# Check FFmpeg installation\nffmpeg -version\n\n# Test on device\nflutter run -d android --verbose\n```\n\n#### Timeout During Video Import (50+ files)\nThe import timeout scales automatically: **30 + (file count) seconds**. For 100 files, timeout is 130 seconds.\n\n#### Out of Memory on Large Videos\n- Close other apps\n- Reduce target resolution\n- Clear app cache: Settings \u003e Clear Cache\n\n#### Dark Mode Not Working\nEnsure device has:\n1. \"Use system theme\" enabled in Settings\n2. System dark mode activated (Android 9+)\n\n---\n\n## Dependency Management\n\n### Core Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| **flutter** | 3.32.8 | UI framework |\n| **flutter_riverpod** | 2.6.1 | State management |\n| **go_router** | 16.2.0 | Navigation |\n| **ffmpeg_kit_flutter_new** | 4.1.0 | Video processing |\n| **video_thumbnail** | 0.5.6 | Thumbnail generation |\n| **file_picker** | 10.3.3 | File selection |\n| **permission_handler** | 12.0.1 | Permission requests |\n| **flex_color_scheme** | 8.3.1 | Material 3 theming |\n| **phosphor_flutter** | 2.1.0 | Icons (600+) |\n| **path_provider** | 2.1.5 | App directories |\n| **shared_preferences** | 2.5.3 | Persistent settings |\n| **crypto** | 3.0.7 | Cryptographic utilities |\n| **package_info_plus** | 8.0.2 | Package information |\n| **logger** | 2.6.2 | Logging |\n\n### Dev Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| **flutter_test** | SDK | Testing framework |\n| **integration_test** | SDK | Integration tests |\n| **flutter_lints** | 4.0.0 | Code analysis |\n\nCheck `pubspec.yaml` for complete dependency list.\n\n---\n\n## Architecture Decisions\n\n### Why Riverpod?\n- Type-safe without BuildContext\n- Excellent async handling (FutureProvider)\n- Scoped state with `.family`\n- Testable without mocking frameworks\n\n### Why GoRouter?\n- Type-safe route parameters\n- Deep linking support\n- Declarative routing tree\n- Nested navigation for tablets\n\n### Why FFmpeg?\n- Industry standard (used by YouTube, Instagram)\n- Supports 100+ codecs/containers\n- Hardware acceleration support\n- Active community and updates\n\n### Platform-Specific Implementation\n- **_mobile.dart** files for Android-specific logic (MediaCodec, MediaStore, MediaStore URI resolution)\n- Optimized for Android 7.0+ with hardware acceleration support\n\n---\n\n## Contributing\n\nContributions welcome! Please:\n\n1. **Fork repository** and create feature branch\n2. **Code** following established patterns (see Development section)\n3. **Test** thoroughly (unit, widget, integration)\n4. **Format** with `flutter format lib/`\n5. **Analyze** with `flutter analyze` (0 warnings)\n6. **Submit PR** with clear description\n\n### Areas for Contribution\n\n- [ ] Additional compression algorithms\n- [ ] More language translations\n- [ ] Performance benchmarks\n- [ ] Accessibility improvements\n\n---\n\n## License\n\nMIT License - See LICENSE file for details.\n\n---\n\n**Built with ❤️ using Flutter**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froymejia2217%2Fvcompress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froymejia2217%2Fvcompress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froymejia2217%2Fvcompress/lists"}