Acid Cam Dev Container - Complete Setup Guide

📋 Overview

The acidcam-dev container is a pre-configured development environment that packages all the Acid Cam video effects applications along with their dependencies. This containerized approach ensures consistent behavior across different Linux distributions and eliminates the complexity of manually compiling and configuring these applications.

🎬 Acid Cam v2 Qt

A powerful Qt-based video effects application with an intuitive graphical interface. Supports real-time video processing with hundreds of built-in filters and effects.

⚡ AcidCamGL

OpenGL-accelerated video effects engine providing superior performance through GPU-based rendering. Ideal for high-resolution video processing.

🔀 Glitch GUI

Specialized tool for creating glitch art and databending effects. Transform ordinary videos into striking visual experiments.

💡

Why Use Containers?
Containers provide isolated environments with all dependencies pre-installed. This means no library conflicts, consistent behavior across systems, and easy cleanup when you're done.

🖥️ Understanding CUDA vs Standard Builds

One of the most important decisions when using Acid Cam is choosing between the CUDA-enabled build and the standard build. This choice significantly impacts performance, especially when encoding video output.

CUDA / NVENC NVIDIA GPU Acceleration

CUDA (Compute Unified Device Architecture) is NVIDIA's parallel computing platform. When combined with NVENC (NVIDIA Encoder), it enables hardware-accelerated video encoding directly on the GPU.

Video encoding happens on dedicated GPU hardware
CPU remains free for other tasks and effects processing
Encoding speeds 3-10x faster than software encoding
Lower power consumption for encoding tasks
Requires NVIDIA GTX 600 series or newer
Needs NVIDIA Container Toolkit for container access

Software CPU-Based Processing

Standard builds use software-based encoding through libraries like libx264 and libx265. All processing happens on the CPU using highly optimized algorithms.

Works on any CPU without special hardware
Excellent output quality with fine-grained control
Compatible with Intel, AMD, and ARM processors
No additional driver requirements
Higher CPU usage during encoding
Slower encoding but sometimes better compression

Video Encoder Comparison

Understanding the different encoders available helps you make the best choice for your workflow. Here's a detailed comparison:

Encoder	Type	Hardware	Speed	Quality	Best For
`h264_nvenc`	Hardware (NVIDIA)	GTX 600+	⚡⚡⚡⚡⚡	★★★★☆	Real-time encoding, streaming
`hevc_nvenc`	Hardware (NVIDIA)	GTX 900+	⚡⚡⚡⚡⚡	★★★★☆	4K video, smaller file sizes
`libx264`	Software (CPU)	Any CPU	⚡⚡☆☆☆	★★★★★	Maximum quality, archival
`libx265`	Software (CPU)	Any CPU	⚡☆☆☆☆	★★★★★	Best compression, 4K archival
`h264_vaapi`	Hardware (Intel/AMD)	Intel HD / AMD GPU	⚡⚡⚡⚡☆	★★★★☆	Intel/AMD systems

When to Choose Each Option

Use NVENC (CUDA)

Hardware Encoding

Choose this when you have an NVIDIA GPU and need fast encoding. Perfect for:

Live streaming your effects
Processing many videos in batch
Real-time video capture with effects
When CPU is needed for other tasks

Encoding Speed

Use libx264/libx265

Software Encoding

Choose this when quality is paramount or you don't have NVIDIA hardware:

Creating final renders for distribution
Maximum compression efficiency needed
Using AMD or Intel integrated graphics
Archival quality requirements

Encoding Speed

🎮

NVIDIA Users: To use NVENC encoding within containers, you must install the NVIDIA Container Toolkit. This allows the container to access your GPU's encoding capabilities.

🔧 Prerequisites

Before setting up the acidcam-dev container, ensure your system meets the following requirements:

Required Software

1 Install Podman

Podman is a daemonless container engine that's compatible with Docker. It runs containers without requiring root privileges.

# Arch Linux
sudo pacman -S podman

# Ubuntu / Debian
sudo apt install podman

# Fedora
sudo dnf install podman

# Verify installation
podman --version

2 Install X11 Utilities

The xhost command is needed to grant the container permission to display graphics on your screen.

# Arch Linux
sudo pacman -S xorg-xhost

# Ubuntu / Debian
sudo apt install x11-xserver-utils

# Fedora
sudo dnf install xorg-x11-server-utils

3 GPU Drivers (Required)

Proper GPU drivers are essential for hardware acceleration. Install the appropriate drivers for your graphics card:

# NVIDIA (Arch Linux)
sudo pacman -S nvidia nvidia-utils

# AMD / Intel (Arch Linux - Mesa drivers)
sudo pacman -S mesa vulkan-radeon # AMD
sudo pacman -S mesa vulkan-intel # Intel

# Verify GPU access
ls -la /dev/dri/

4 NVIDIA Container Toolkit (CUDA Users Only)

If you want to use NVENC hardware encoding, install the NVIDIA Container Toolkit:

# Add NVIDIA repository (Ubuntu/Debian)
distribution=$(. /etc/os-release; echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# Install toolkit
sudo apt update
sudo apt install nvidia-container-toolkit

# Configure for Podman
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

# Verify
nvidia-ctk --version

Optional Requirements

📹 Webcam

For live video input and real-time effects. Usually available at /dev/video0. Check with ls /dev/video*

🎵 Audio Device

For audio-reactive effects (if supported). Requires PulseAudio or PipeWire socket mounting.

🚀 Installation & Setup

Quick Start Installation

Follow these steps to get up and running in minutes:

1 Clone the Repository

Download the launcher scripts from GitHub:

git clone https://github.com/lostjared/acidcam-dev.git
cd acidcam-dev

2 Pull the Container Image

Download the pre-built container image from GitHub Container Registry:

# Standard build (recommended for most users)
podman pull ghcr.io/lostjared/acidcam-dev:latest

# Check the downloaded image
podman images | grep acidcam

📦

Image Size: The container image is approximately 2-3 GB as it includes all development tools, libraries, and pre-compiled applications.

3 Make Scripts Executable

Grant execute permissions to all launcher scripts:

chmod +x *.sh

# Verify permissions
ls -la *.sh

4 Create Shared Directory

The scripts automatically create this, but you can do it manually:

mkdir -p ~/container_share

# This folder will be accessible inside the container at:
# /home/developer/share

5 Allow X11 Display Access

Grant the container permission to display on your screen:

# Allow your user (more secure)
xhost +si:localuser:$(whoami)

# Or allow all local connections
xhost +local:

6 Launch an Application!

You're ready to go! Choose an application to run:

# Launch Acid Cam v2 Qt
./AcidCam.v2.sh

# Launch AcidCamGL
./acidcamGL.sh

# Launch Glitch GUI
./glitch.gui.sh

Decision Flowchart

🎬 Want to use Acid Cam?

↓

Do you have an NVIDIA GPU?

↓ Yes

Install NVIDIA Container Toolkit
Use h264_nvenc for encoding

↓ No

Use standard image
Use libx264 for encoding

📱 Available Applications

Acid Cam v2 Qt

The flagship application featuring a comprehensive Qt-based interface. Perfect for users who prefer a traditional desktop application experience with menus, toolbars, and visual controls.

# Launch command
./AcidCam.v2.sh

Feature	Description
Real-time Preview	See effects applied instantly as you adjust parameters
Filter Stacking	Combine multiple filters for complex effect chains
Camera Input	Process live webcam feed with effects
Video Export	Save processed videos in various formats
Preset System	Save and load your favorite effect combinations

AcidCamGL

The OpenGL-accelerated version leverages your GPU for rendering effects. This provides significantly better performance, especially for complex shaders and high-resolution video.

# Launch command
./acidcamGL.sh

⚡

Performance Tip: AcidCamGL typically provides 2-5x better performance compared to CPU-based processing, making it ideal for 1080p and 4K video processing.

Glitch GUI

A specialized tool focused on glitch art aesthetics. Create databending effects, pixel sorting, channel shifting, and other creative digital artifacts.

# Launch command
./glitch.gui.sh

File Sharing Between Host and Container

All applications can access files in the shared folder. This is your bridge for importing and exporting media:

# Copy a video into the container share
cp my_video.mp4 ~/container_share/

# Inside the application, navigate to:
# /home/developer/share/my_video.mp4

# Exported files will appear in:
ls ~/container_share/

📥 Importing Files

Place your video files, images, or project files in ~/container_share on your host. They'll appear at /home/developer/share inside the container.

📤 Exporting Files

When saving or exporting from the applications, save to /home/developer/share. Files will appear in ~/container_share on your host.

🎬 Video Encoding Deep Dive

Understanding video encoding is crucial for getting the best results from Acid Cam. This section explains the technical details of different encoding options.

H.264 Encoding Options

Software Encoding: libx264

The libx264 encoder is a highly optimized software implementation of the H.264/AVC standard. It's known for excellent compression efficiency and quality.

# Example FFmpeg command using libx264
ffmpeg -i input.mp4 -c:v libx264 -preset medium -crf 23 output.mp4

# Preset options: ultrafast, superfast, veryfast, faster, fast,
#                medium (default), slow, slower, veryslow

# CRF (quality): 0 = lossless, 23 = default, 51 = worst
# Lower values = better quality but larger files

Preset	Encoding Speed	File Size	Recommended Use
ultrafast	Fastest	Largest	Quick previews, testing
medium	Balanced	Balanced	General purpose (default)
slow	Slow	Smaller	Final renders, distribution
veryslow	Slowest	Smallest	Archival, maximum quality

Hardware Encoding: h264_nvenc

NVIDIA's NVENC encoder uses dedicated silicon on the GPU for video encoding. This offloads the work from your CPU and provides exceptional encoding speeds.

# Example FFmpeg command using h264_nvenc
ffmpeg -i input.mp4 -c:v h264_nvenc -preset p4 -cq 23 output.mp4

# NVENC presets (fastest to slowest):
# p1 (fastest), p2, p3, p4 (medium), p5, p6, p7 (slowest/best quality)

# CQ mode: Similar to CRF, lower = better quality
# -cq 19 is high quality, -cq 23 is good balance

📊

NVENC Performance:

GTX 1080: ~500+ FPS for 1080p encoding
RTX 3080: ~800+ FPS for 1080p encoding
RTX 4090: ~1200+ FPS for 1080p encoding

Compare this to libx264 which typically achieves 30-100 FPS depending on preset.

H.265/HEVC Encoding

HEVC (High Efficiency Video Coding) provides approximately 50% better compression than H.264 at the same quality level. However, it requires more processing power to encode and decode.

# Software HEVC encoding
ffmpeg -i input.mp4 -c:v libx265 -preset medium -crf 28 output.mp4

# Hardware HEVC encoding (NVIDIA)
ffmpeg -i input.mp4 -c:v hevc_nvenc -preset p4 -cq 28 output.mp4

# Note: HEVC uses higher CRF values for equivalent quality
# CRF 28 in HEVC ≈ CRF 23 in H.264

Choosing the Right Encoder

What's your priority?

⚡ Speed

Use h264_nvenc
Requires NVIDIA GPU

📦 File Size

Use libx265 or
hevc_nvenc

⭐ Quality

Use libx264
Preset: slow/veryslow

🔍 Troubleshooting

Display & Graphics Issues

Error: "Cannot open display" or "No display specified"

# Solution 1: Allow X11 connections
xhost +local:

# Solution 2: Check DISPLAY variable
echo $DISPLAY  # Should show something like ":0" or ":1"

# Solution 3: Export DISPLAY if not set
export DISPLAY=:0

Black screen or graphical glitches

# Check GPU driver status
glxinfo | grep "OpenGL renderer"

# Verify DRI device access
ls -la /dev/dri/

# For NVIDIA, check driver version
nvidia-smi

Container Issues

Container fails to start

# Check for existing containers with same name
podman ps -a | grep acidcam

# Remove stopped containers
podman rm acidcam-update-dev

# Force remove if needed
podman rm -f acidcam-update-dev

Permission denied errors

# Check Podman rootless setup
podman info | grep -i rootless

# Reset Podman storage if corrupted
podman system reset

# Ensure user namespaces are enabled
cat /proc/sys/kernel/unprivileged_userns_clone  # Should be 1

Webcam Issues

Webcam not detected

# List video devices
ls -la /dev/video*

# Check webcam with v4l2
v4l2-ctl --list-devices

# If using a different device (e.g., /dev/video2),
# modify the script: --device /dev/video2

NVIDIA / CUDA Issues

NVENC not available in container

# Verify NVIDIA Container Toolkit is installed
nvidia-ctk --version

# Generate CDI specification
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

# Test GPU access in container
podman run --rm --device nvidia.com/gpu=all nvidia/cuda:12.0-base nvidia-smi

# Add to script if needed:
# --device nvidia.com/gpu=all

⚠️

Common CUDA Pitfall: Make sure your NVIDIA driver version is compatible with the CUDA version in the container. Run nvidia-smi to check your driver's maximum supported CUDA version.

Audio Issues

No audio or audio passthrough needed

# For PulseAudio, add to podman run command:
-v /run/user/$(id -u)/pulse:/run/user/1000/pulse

# For PipeWire:
-v /run/user/$(id -u)/pipewire-0:/run/user/1000/pipewire-0

Getting Help

If you're still experiencing issues:

Check the GitHub Issues page for known problems
Create a new issue with detailed error messages and system information
Include output from: podman info, nvidia-smi (if applicable)