Development Setup¶

Set up your Fluvie development environment

This guide walks you through setting up a complete development environment for contributing to Fluvie.

Table of Contents¶

Prerequisites
Repository Setup
IDE Configuration
Running the Project
Project Structure
Common Tasks

Prerequisites¶

Required¶

Tool	Version	Installation
Flutter	3.16+	flutter.dev
Dart	3.2+	Included with Flutter
Git	2.x	git-scm.com
FFmpeg	5.x+	See FFmpeg Setup

Recommended¶

Tool	Purpose
VS Code	Recommended IDE with Flutter extension
Android Studio	Alternative IDE, required for Android emulators

Verify Installation¶

# Check Flutter
flutter --version
# Flutter 3.16.0 or higher

# Check Dart
dart --version
# Dart SDK version: 3.2.0 or higher

# Check FFmpeg
ffmpeg -version
# ffmpeg version 5.x or higher

# Check Flutter doctor
flutter doctor
# All checks should pass

Repository Setup¶

1. Fork and Clone¶

# Fork the repository on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/fluvie.git
cd fluvie

# Add upstream remote
git remote add upstream https://github.com/anthropics/fluvie.git

2. Install Dependencies¶

# Install main package dependencies
flutter pub get

# Install example app dependencies
cd example
flutter pub get
cd ..

3. Verify Setup¶

# Run tests to verify everything works
flutter test

# Should see all tests passing

IDE Configuration¶

VS Code (Recommended)¶

Extensions¶

Install these extensions:

Dart - Dart language support
Flutter - Flutter development tools
Flutter Intl - Internationalization (optional)
GitLens - Git integration (optional)

Settings¶

Create or update .vscode/settings.json:

{
  "dart.lineLength": 80,
  "editor.formatOnSave": true,
  "editor.rulers": [80],
  "[dart]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "Dart-Code.dart-code"
  }
}

Launch Configuration¶

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Example App",
      "cwd": "example",
      "request": "launch",
      "type": "dart"
    },
    {
      "name": "Run Tests",
      "request": "launch",
      "type": "dart",
      "program": "test/"
    }
  ]
}

Android Studio¶

Open the project folder
Go to File > Settings > Languages & Frameworks > Dart
Set SDK path to your Flutter installation
Enable Format code on save

Running the Project¶

Run Tests¶

# All tests
flutter test

# Specific test file
flutter test test/fluvie_test.dart

# With verbose output
flutter test --reporter expanded

# With coverage
flutter test --coverage
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html

Run Example App¶

cd example

# Run on connected device/emulator
flutter run

# Run on specific device
flutter run -d chrome  # Web
flutter run -d macos   # macOS
flutter run -d linux   # Linux

Run Specific Examples¶

The example app has a gallery of examples:

cd example
flutter run

# Navigate to Gallery > Select Example

Generate Code¶

If you modify code that uses code generation:

# Run build_runner
dart run build_runner build

# Or watch for changes
dart run build_runner watch

Project Structure¶

fluvie/
├── lib/
│   ├── fluvie.dart              # Main export file
│   ├── declarative.dart         # Declarative API exports
│   └── src/
│       ├── capture/             # Frame capture system
│       │   └── frame_sequencer.dart
│       ├── config/              # Configuration classes
│       ├── declarative/         # Declarative widgets (V-prefixed)
│       ├── domain/              # Domain models
│       │   ├── render_config.dart
│       │   ├── audio_config.dart
│       │   └── ...
│       ├── encoding/            # FFmpeg integration
│       │   ├── video_encoder_service.dart
│       │   ├── ffmpeg_filter_graph_builder.dart
│       │   └── ffmpeg_provider/
│       ├── integration/         # Main render service
│       │   └── render_service.dart
│       ├── presentation/        # Core widgets
│       │   ├── video_composition.dart
│       │   ├── scene.dart
│       │   ├── time_consumer.dart
│       │   └── ...
│       ├── preview/             # Preview mode components
│       ├── templates/           # Pre-built templates
│       │   ├── intro/
│       │   ├── ranking/
│       │   ├── data_viz/
│       │   ├── collage/
│       │   ├── thematic/
│       │   └── conclusion/
│       └── utils/               # Utility functions
│
├── example/
│   ├── lib/
│   │   ├── main.dart           # Example app entry
│   │   └── gallery/            # Example gallery
│   │       └── examples/       # Individual examples
│   └── test/
│       └── widget_test.dart
│
├── test/
│   ├── features/               # Gherkin feature tests
│   │   ├── step/               # Step definitions
│   │   └── *.feature           # Feature files
│   ├── presentation/           # Widget tests
│   └── *.dart                  # Unit tests
│
├── doc/                        # Documentation
│   ├── README.md
│   └── ...
│
├── pubspec.yaml               # Package configuration
├── analysis_options.yaml      # Linter configuration
└── README.md                  # Project README

Common Tasks¶

Create widget in lib/src/presentation/
Export from lib/fluvie.dart
Add tests in test/
Add documentation in doc/widgets/
Add example usage in example/

Adding a New Template¶

Create data class in lib/src/templates/
Create template widget extending WrappedTemplate
Add to appropriate category folder
Export from lib/fluvie.dart
Add tests
Document in doc/templates/

Adding a New Animation¶

Create in lib/src/presentation/ or lib/src/utils/
If PropAnimation, add as static factory
Add tests
Document in doc/animations/

Updating Documentation¶

Documentation is in doc/
Follow existing format with Table of Contents
Include code examples
Link to related documentation

Keeping Your Fork Updated¶

# Fetch upstream changes
git fetch upstream

# Merge into your main branch
git checkout main
git merge upstream/main

# Push to your fork
git push origin main

Troubleshooting¶

Flutter Doctor Issues¶

flutter doctor -v
# Follow the suggestions for any issues

FFmpeg Not Found¶

Ensure FFmpeg is in your PATH:

# Check if FFmpeg is accessible
which ffmpeg

# If not found, add to PATH or reinstall

Tests Failing¶

# Clear Flutter cache
flutter clean
flutter pub get

# Regenerate code
dart run build_runner build --delete-conflicting-outputs

# Run tests again
flutter test

Example App Not Running¶

cd example
flutter clean
flutter pub get
flutter run

Testing - Testing guidelines
Code Style - Coding standards
Contributing - Contribution overview