diff --git a/DONE.md b/DONE.md index 75d4b1b..e740051 100644 --- a/DONE.md +++ b/DONE.md @@ -3,6 +3,11 @@ ## Version 0.1.0-dev22 (2026-01-01) - Documentation Overhaul ### Documentation +- ✅ **Addressed Platform Gaps (Windows Guide)** + - Created a new, comprehensive installation guide for native Windows (`docs/INSTALL_WINDOWS.md`). + - Refactored the main `INSTALLATION.md` into a platform-agnostic hub that now links to the separate, detailed guides for Windows and Linux/macOS. + - This provides a clear, user-friendly path for users on all major platforms. + - ✅ **Aligned Documentation with Reality** - Audited and tagged all planned features in the documentation with `[PLANNED]`. - This provides a more honest representation of the project's capabilities. diff --git a/TODO.md b/TODO.md index bc85f84..85f0f9d 100644 --- a/TODO.md +++ b/TODO.md @@ -2,14 +2,14 @@ This file tracks upcoming features, improvements, and known issues. -## Documentation: Address Platform Gaps +## Documentation: Fix Structural Errors **Priority:** High -- [ ] **Create Native Windows Guide:** - - Create a comprehensive installation and usage guide for native Windows. - - This guide should be on par with the existing Linux guide. - - Refactor `INSTALLATION.md` to be a central hub linking to platform-specific instructions. +- [ ] **Audit All Docs for Broken Links:** + - Systematically check all 46 `.md` files for internal links that point to non-existent files or sections. + - Create placeholder stubs for missing documents that are essential (e.g., `CONTRIBUTING.md`) or remove the links if they are not. + - This ensures a professional and navigable documentation experience. ## Critical Priority: dev22 diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index ebef72e..6cc219b 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -1,375 +1,36 @@ # VideoTools Installation Guide -This guide will help you install VideoTools with minimal setup. - -## Quick Start (Recommended for Most Users) - -### One-Command Installation - -```bash -bash scripts/install.sh -``` - -That's it! The installer will: - -1. ✅ Check your Go installation -2. ✅ Build VideoTools from source -3. ✅ Install the binary to your system -4. ✅ Set up shell aliases automatically -5. ✅ Configure your shell environment - -### After Installation - -Reload your shell: - -```bash -# For bash users: -source ~/.bashrc - -# For zsh users: -source ~/.zshrc -``` - -Then start using VideoTools: - -```bash -VideoTools -``` +Welcome to the VideoTools installation guide. Please select your operating system to view the detailed instructions. --- -## Installation Options +## Supported Platforms -### Option 1: System-Wide Installation (Recommended for Shared Computers) +### 🖥️ Windows -```bash -bash scripts/install.sh -# Select option 1 when prompted -# Enter your password if requested -``` +For Windows 10 and 11, please follow our detailed, step-by-step guide. It covers both automated and manual setup. -**Advantages:** -- ✅ Available to all users on the system -- ✅ Binary in standard system path -- ✅ Professional setup +- **[➡️ View Windows Installation Guide](./INSTALL_WINDOWS.md)** -**Requirements:** -- Sudo access (for system-wide installation) +### 🐧 Linux & macOS + +For Linux (Ubuntu, Fedora, Arch, etc.), macOS, and Windows Subsystem for Linux (WSL), the installation is handled by a single, powerful script. + +- **[➡️ View Linux, macOS, & WSL Installation Guide](./INSTALL_LINUX.md)** --- -### Option 2: User-Local Installation (Recommended for Personal Use) +## General Requirements -```bash -bash scripts/install.sh -# Select option 2 when prompted (default) -``` +Before you begin, ensure your system meets these basic requirements: -**Advantages:** -- ✅ No sudo required -- ✅ Works immediately -- ✅ Private to your user account -- ✅ No administrator needed - -**Requirements:** -- None - works on any system! +- **Go:** Version 1.21 or later is required to build the application. +- **FFmpeg:** Required for all video and audio processing. Our platform-specific guides cover how to install this. +- **Disk Space:** At least 2 GB of free disk space for the application and its dependencies. +- **Internet Connection:** Required for downloading dependencies during the build process. --- -## What the Installer Does +## Development -The `scripts/install.sh` script performs these steps: - -### Step 1: Go Verification -- Checks if Go 1.21+ is installed -- Displays Go version -- Exits with helpful error message if not found - -### Step 2: Build -- Cleans previous builds -- Downloads dependencies -- Compiles VideoTools binary -- Validates build success - -### Step 3: Installation Path Selection -- Presents two options: - - System-wide (`/usr/local/bin`) - - User-local (`~/.local/bin`) -- Creates directories if needed - -### Step 4: Binary Installation -- Copies binary to selected location -- Sets proper file permissions (755) -- Validates installation - -### Step 5: Shell Environment Setup -- Detects your shell (bash/zsh) -- Adds VideoTools installation path to PATH -- Sources alias script for convenience commands -- Adds to appropriate rc file (`.bashrc` or `.zshrc`) - ---- - -## Convenience Commands - -After installation, you'll have access to: - -```bash -VideoTools # Run VideoTools directly -VideoToolsRebuild # Force rebuild from source -VideoToolsClean # Clean build artifacts and cache -``` - ---- - -## Development Workflow - -For day-to-day development: - -```bash -./scripts/build.sh -./scripts/run.sh -``` - -Use `./scripts/install.sh` when you add new system dependencies or want to reinstall. - -## Roadmap - -See `docs/ROADMAP.md` for the current dev focus and priorities. - ---- - -## Requirements - -### Essential -- **Go 1.21 or later** - https://go.dev/dl/ -- **Bash or Zsh** shell - -### Optional -- **FFmpeg** (for actual video encoding) - ```bash - ffmpeg -version - ``` - -### System -- Linux, macOS, or Windows (native) -- At least 2 GB free disk space -- Stable internet connection (for dependencies) - ---- - -## Troubleshooting - -### "Go is not installed" - -**Solution:** Install Go from https://go.dev/dl/ - -```bash -# After installing Go, verify: -go version -``` - -### Build Failed - -**Solution:** Check build log for specific errors: - -```bash -bash scripts/install.sh -# Look for error messages in the build log output -``` - -### Installation Path Not in PATH - -If you see this warning: - -``` -Warning: ~/.local/bin is not in your PATH -``` - -**Solution:** Reload your shell: - -```bash -source ~/.bashrc # For bash -source ~/.zshrc # For zsh -``` - -Or manually add to your shell configuration: - -```bash -# Add this line to ~/.bashrc or ~/.zshrc: -export PATH="$HOME/.local/bin:$PATH" -``` - -### "Permission denied" on binary - -**Solution:** Ensure file has correct permissions: - -```bash -chmod +x ~/.local/bin/VideoTools -# or for system-wide: -ls -l /usr/local/bin/VideoTools -``` - -### Aliases Not Working - -**Solution:** Ensure alias script is sourced: - -```bash -# Check if this line is in your ~/.bashrc or ~/.zshrc: -source /path/to/VideoTools/scripts/alias.sh - -# If not, add it manually: -echo 'source /path/to/VideoTools/scripts/alias.sh' >> ~/.bashrc -source ~/.bashrc -``` - ---- - -## Advanced: Manual Installation - -If you prefer to install manually: - -### Step 1: Build - -```bash -cd /path/to/VideoTools -CGO_ENABLED=1 go build -o VideoTools . -``` - -### Step 2: Install Binary - -```bash -# User-local installation: -mkdir -p ~/.local/bin -cp VideoTools ~/.local/bin/VideoTools -chmod +x ~/.local/bin/VideoTools - -# System-wide installation: -sudo cp VideoTools /usr/local/bin/VideoTools -sudo chmod +x /usr/local/bin/VideoTools -``` - -### Step 3: Setup Aliases - -```bash -# Add to ~/.bashrc or ~/.zshrc: -source /path/to/VideoTools/scripts/alias.sh - -# Add to PATH if needed: -export PATH="$HOME/.local/bin:$PATH" -``` - -### Step 4: Reload Shell - -```bash -source ~/.bashrc # for bash -source ~/.zshrc # for zsh -``` - ---- - -## Uninstallation - -### If Installed System-Wide - -```bash -sudo rm /usr/local/bin/VideoTools -``` - -### If Installed User-Local - -```bash -rm ~/.local/bin/VideoTools -``` - -### Remove Shell Configuration - -Remove these lines from `~/.bashrc` or `~/.zshrc`: - -```bash -# VideoTools installation path -export PATH="$HOME/.local/bin:$PATH" - -# VideoTools convenience aliases -source "/path/to/VideoTools/scripts/alias.sh" -``` - ---- - -## Verification - -After installation, verify everything works: - -```bash -# Check binary is accessible: -which VideoTools - -# Check version/help: -VideoTools --help - -# Check aliases are available: -type VideoToolsRebuild -type VideoToolsClean -``` - ---- - -## Getting Help - -For issues or questions: - -1. Check **BUILD_AND_RUN.md** for build-specific help -2. Check **DVD_USER_GUIDE.md** for usage help -3. Review installation logs in `/tmp/videotools-build.log` -4. Check shell configuration files for errors - ---- - -## Next Steps - -After successful installation: - -1. **Read the Quick Start Guide:** - ```bash - cat DVD_USER_GUIDE.md - ``` - -2. **Launch VideoTools:** - ```bash - VideoTools - ``` - -3. **Convert your first video:** - - Go to Convert module - - Load a video - - Select "DVD-NTSC (MPEG-2)" or "DVD-PAL (MPEG-2)" - - Click "Add to Queue" - - Click "View Queue" → "Start Queue" - ---- - -## Platform-Specific Notes - -### Linux (Ubuntu/Debian) - -Installation is fully automatic. The script handles all steps. - -### Linux (Arch/Manjaro) - -Same as above. Installation works without modification. - -### macOS - -Installation works but requires Xcode Command Line Tools: - -```bash -xcode-select --install -``` - -### Windows (WSL) - -Installation works in WSL environment. Ensure you have WSL with Linux distro installed. - ---- - -Enjoy using VideoTools! 🎬 +If you are a developer looking to contribute to the project, please see the [Build and Run Guide](./BUILD_AND_RUN.md) for instructions on setting up a development environment. diff --git a/docs/INSTALL_LINUX.md b/docs/INSTALL_LINUX.md new file mode 100644 index 0000000..b66e4d1 --- /dev/null +++ b/docs/INSTALL_LINUX.md @@ -0,0 +1,107 @@ +# VideoTools Installation Guide for Linux, macOS, & WSL + +This guide provides detailed instructions for installing VideoTools on Linux, macOS, and Windows Subsystem for Linux (WSL) using the automated script. + +--- + +## One-Command Installation + +The recommended method for all Unix-like systems is the `install.sh` script. + +```bash +bash scripts/install.sh +``` + +This single command automates the entire setup process. + +### What the Installer Does + +1. **Go Verification:** Checks if Go (version 1.21 or later) is installed and available in your `PATH`. +2. **Build from Source:** Cleans any previous builds, downloads all necessary Go dependencies, and compiles the `VideoTools` binary. +3. **Path Selection:** Prompts you to choose an installation location: + * **System-wide:** `/usr/local/bin` (Requires `sudo` privileges). Recommended for multi-user systems. + * **User-local:** `~/.local/bin` (Default). Recommended for most users as it does not require `sudo`. +4. **Install Binary:** Copies the compiled binary to the selected location and makes it executable. +5. **Configure Shell:** Detects your shell (`bash` or `zsh`) and updates the corresponding resource file (`~/.bashrc` or `~/.zshrc`) to: + * Add the installation directory to your `PATH`. + * Source the `alias.sh` script for convenience commands. + +### After Installation + +You must reload your shell for the changes to take effect: + +```bash +# For bash users: +source ~/.bashrc + +# For zsh users: +source ~/.zshrc +``` + +You can now run the application from anywhere by simply typing `VideoTools`. + +--- + +## Convenience Commands + +The installation script sets up a few helpful aliases: + +- `VideoTools`: Runs the main application. +- `VideoToolsRebuild`: Forces a full rebuild of the application from source. +- `VideoToolsClean`: Cleans all build artifacts and clears the Go cache for the project. + +--- + +## Manual Installation + +If you prefer to perform the steps manually: + +1. **Build the Binary:** + ```bash + CGO_ENABLED=1 go build -o VideoTools . + ``` + +2. **Install the Binary:** + * **User-local:** + ```bash + mkdir -p ~/.local/bin + cp VideoTools ~/.local/bin/ + ``` + * **System-wide:** + ```bash + sudo cp VideoTools /usr/local/bin/ + ``` + +3. **Update Shell Configuration:** + Add the following lines to your `~/.bashrc` or `~/.zshrc` file, replacing `/path/to/VideoTools` with the actual absolute path to the project directory. + + ```bash + # Add VideoTools to PATH + export PATH="$HOME/.local/bin:$PATH" + + # Source VideoTools aliases + source /path/to/VideoTools/scripts/alias.sh + ``` + +4. **Reload Your Shell:** + ```bash + source ~/.bashrc # Or source ~/.zshrc + ``` + +--- + +## Uninstallation + +1. **Remove the Binary:** + * If installed user-locally: `rm ~/.local/bin/VideoTools` + * If installed system-wide: `sudo rm /usr/local/bin/VideoTools` + +2. **Remove Shell Configuration:** + Open your `~/.bashrc` or `~/.zshrc` file and remove the lines that were added for `VideoTools`. + +--- + +## Platform-Specific Notes + +- **macOS:** You may need to install Xcode Command Line Tools first by running `xcode-select --install`. +- **WSL:** The Linux instructions work without modification inside a WSL environment. diff --git a/docs/INSTALL_WINDOWS.md b/docs/INSTALL_WINDOWS.md new file mode 100644 index 0000000..2d17a0a --- /dev/null +++ b/docs/INSTALL_WINDOWS.md @@ -0,0 +1,96 @@ +# VideoTools Installation Guide for Windows + +This guide provides step-by-step instructions for installing VideoTools on Windows 10 and 11. + +--- + +## Method 1: Automated Installation (Recommended) + +This method uses a script to automatically download and configure all necessary dependencies. + +### Step 1: Download the Project + +If you haven't already, download the project files as a ZIP and extract them to a folder on your computer (e.g., `C:\Users\YourUser\Documents\VideoTools`). + +### Step 2: Run the Setup Script + +1. Open the project folder in File Explorer. +2. Find and double-click on `setup-windows.bat`. +3. A terminal window will open and run the PowerShell setup script. This will: + * **Download FFmpeg:** The script automatically fetches the latest stable version of FFmpeg, which is required for all video operations. + * **Install Dependencies:** It places the necessary files in the correct directories. + * **Configure for Portability:** By default, it sets up VideoTools as a "portable" application, meaning all its components (like `ffmpeg.exe`) are stored directly within the project's `scripts/` folder. + +> **Note:** If Windows Defender SmartScreen appears, click "More info" and then "Run anyway". This is expected as the application is not yet digitally signed. + +### Step 3: Run VideoTools + +Once the script finishes, you can run the application by double-clicking `run.bat` in the main project folder. + +--- + +## Method 2: Manual Installation + +If you prefer to set up the dependencies yourself, follow these steps. + +### Step 1: Download and Install Go + +1. **Download:** Go to the official Go website: [go.dev/dl/](https://go.dev/dl/) +2. **Install:** Run the installer and follow the on-screen instructions. +3. **Verify:** Open a Command Prompt and type `go version`. You should see the installed Go version. + +### Step 2: Download FFmpeg + +FFmpeg is the engine that powers VideoTools. + +1. **Download:** Go to the recommended FFmpeg builds page: [github.com/BtbN/FFmpeg-Builds/releases](https://github.com/BtbN/FFmpeg-Builds/releases) +2. Download the file named `ffmpeg-master-latest-win64-gpl.zip`. + +### Step 3: Place FFmpeg Files + +You have two options for where to place the FFmpeg files: + +#### Option A: Bundle with VideoTools (Portable) + +This is the easiest option. + +1. Open the downloaded `ffmpeg-...-win64-gpl.zip`. +2. Navigate into the `bin` folder inside the zip file. +3. Copy `ffmpeg.exe` and `ffprobe.exe`. +4. Paste them into the root directory of the VideoTools project, right next to `VideoTools.exe` (or `main.go` if you are building from source). + +Your folder should look like this: +``` +\---VideoTools + | VideoTools.exe (or the built executable) + | ffmpeg.exe <-- Copied here + | ffprobe.exe <-- Copied here + | main.go + \---... +``` + +#### Option B: Install System-Wide + +This makes FFmpeg available to all applications on your system. + +1. Extract the entire `ffmpeg-...-win64-gpl.zip` to a permanent location, like `C:\Program Files\ffmpeg`. +2. Add the FFmpeg `bin` directory to your system's PATH environment variable. + * Press the Windows key and type "Edit the system environment variables". + * Click the "Environment Variables..." button. + * Under "System variables", find and select the `Path` variable, then click "Edit...". + * Click "New" and add the path to your FFmpeg `bin` folder (e.g., `C:\Program Files\ffmpeg\bin`). +3. **Verify:** Open a Command Prompt and type `ffmpeg -version`. You should see the version information. + +### Step 4: Build and Run + +1. Open a Command Prompt in the VideoTools project directory. +2. Run the build script: `scripts\build.bat` +3. Run the application: `run.bat` + +--- + +## Troubleshooting + +- **"FFmpeg not found" Error:** This means VideoTools can't locate `ffmpeg.exe`. Ensure it's either in the same folder as `VideoTools.exe` or that the system-wide installation path is correct. +- **Application Doesn't Start:** Make sure you have a 64-bit version of Windows 10 or 11 and that your graphics drivers are up to date. +- **Antivirus Warnings:** Some antivirus programs may flag the unsigned executable. This is a false positive.