feat(docs): create dedicated Windows installation guide
This commit introduces a new, comprehensive installation guide for Windows users (INSTALL_WINDOWS.md) and refactors the main INSTALLATION.md into a platform-agnostic hub. This addresses the documentation gap for the Windows platform, providing clear and distinct instructions for all supported operating systems.
This commit is contained in:
parent
73be76107b
commit
5d07d5bb61
5
DONE.md
5
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.
|
||||
|
|
|
|||
10
TODO.md
10
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
107
docs/INSTALL_LINUX.md
Normal file
107
docs/INSTALL_LINUX.md
Normal file
|
|
@ -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.
|
||||
96
docs/INSTALL_WINDOWS.md
Normal file
96
docs/INSTALL_WINDOWS.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user