3DS Webcam Bridge

Stream your Nintendo 3DS cameras to your PC as a virtual webcam! Support for both mono and stereo (3D) modes using the outer dual cameras.

Features

• 📷 Multiple Camera Modes

  • Inner camera (single lens, mono)
  • Outer cameras (dual lens, mono or stereo)
  • True 3D support with synchronized stereo capture

• 🎥 Stereo Output Modes

  • Off: Left eye only
  • Side-by-Side: Horizontal stereo for 3D displays/VR
  • Anaglyph: Red-cyan 3D glasses
  • Dual: Separate left/right virtual cameras

• 💻 Cross-Platform PC Support

  • Windows 10/11: Via OBS Virtual Camera
  • Linux: Via v4l2loopback + pyvirtualcam/pyfakewebcam/ffmpeg

• ⚡ Real-time Streaming

  • ~15 FPS @ 400×240 per camera
  • JPEG compression for efficient Wi-Fi streaming
  • Auto-reconnect on connection loss

---

📋 Table of Contents

• Security & Ethics Notice
• Quick Start
  • Linux (Ubuntu/Debian)
  • Windows 10/11
  • Building for 3DS
• Usage
  • 3DS Application
  • PC Server Options
• Project Structure
• Requirements
• Troubleshooting
• Documentation
• Contributing
• License

---

⚠️ Security & Ethics Notice

IMPORTANT: This software is intended for personal, educational, and creative use only.

• Privacy: Streaming camera feeds creates privacy risks. Always obtain consent from anyone who may be captured by the cameras.
• Network Security: The stream is not encrypted by default. Only use on trusted networks.
• Responsible Use: Do not use this software for surveillance, harassment, or any illegal activities.
• Children: If used by or around minors, ensure appropriate adult supervision and consent.

By using this software, you accept full responsibility for its use and agree to comply with all applicable laws and regulations.

---

🚀 Quick Start

Linux (Ubuntu/Debian)

1. Install PC Server Dependencies

# Clone or navigate to the repository
cd 3ds-webcam-bridge

# Install dependencies (Python, v4l2loopback, ffmpeg, etc.)
./scripts/pc-install.sh

# Create virtual camera device
./scripts/create-v4l2.sh

# For dual devices (stereo mode):
./scripts/create-v4l2.sh --dual

2. Run the Server

# Mono mode (default)
./pc-server/run_server.sh --device /dev/video0

# Side-by-side stereo
./pc-server/run_server.sh --stereo-mode sbs --width 400 --height 240 --device /dev/video0

# Dual device stereo
./pc-server/run_server.sh --stereo-mode dual --dual-devices /dev/video0,/dev/video1

3. Use in Applications

Open any application that supports webcams (Zoom, OBS, Chrome, etc.) and select:

• Single mode: /dev/video0 (or "3DS Webcam")
• Dual mode: /dev/video0 (Left) and /dev/video1 (Right)

---

Windows 10/11

1. Install PC Server Dependencies

Run PowerShell as Administrator:

# Allow script execution for this session
Set-ExecutionPolicy Bypass -Scope Process -Force

# Navigate to repository
cd 3ds-webcam-bridge

# Run installer (installs Python, OBS Studio, dependencies)
.\scripts\windows\pc-install.ps1 -Port 9000

The installer will:

• ✅ Install Python 3.11 (if needed)
• ✅ Install OBS Studio with Virtual Camera
• ✅ Create Python virtual environment
• ✅ Install Python packages
• ✅ Add firewall rule for TCP port 9000

2. Initialize OBS Virtual Camera

Important first-time step:

1. Launch OBS Studio
2. Go to Tools → VirtualCam → Start
3. Close OBS (the virtual camera will remain available)

3. Run the Server

# Mono mode
.\pc-server\run_server.ps1 -Port 9000 -Device "OBS Virtual Camera"

# Side-by-side stereo
.\pc-server\run_server.ps1 -StereoMode sbs -Width 400 -Height 240 -Device "OBS Virtual Camera"

# Dual device stereo (requires multiple OBS virtual cameras)
.\pc-server\run_server.ps1 -StereoMode dual -DualDevices "OBS Virtual Camera,OBS Virtual Camera 2"

4. Use in Applications

Open any application (Zoom, Discord, Chrome, etc.) and select:

• "OBS Virtual Camera" as your camera device

---

Building for 3DS

1. Install devkitPro (Linux)

# Install devkitPro toolchain
./scripts/install-devkitpro.sh

# Set environment variables (add to ~/.bashrc for persistence)
export DEVKITPRO=/opt/devkitpro
export DEVKITARM=$DEVKITPRO/devkitARM
export PATH=$DEVKITARM/bin:$PATH

# Reload environment
source ~/.bashrc

2. Build the 3DS App

# Build (downloads stb_image_write.h if needed)
./scripts/build-3ds.sh

# Output: dist/3ds-webcam-bridge.3dsx

3. Install on 3DS

1. Copy dist/3ds-webcam-bridge.3dsx to your SD card:

   SD:/3ds/3ds-webcam-bridge/3ds-webcam-bridge.3dsx
   

2. Insert SD card into 3DS

3. Launch Homebrew Launcher

4. Launch 3DS Webcam Bridge

---

📖 Usage

3DS Application

Controls

Button	Action
A	Start/Stop streaming
SELECT	Toggle between Inner/Outer cameras
X	Toggle 3D mode (outer cameras only)
Y	Edit IP address and port
START	Exit application

UI Screens

Top Screen: Status display

• Server IP and port
• Connection status
• Camera mode
• Frame count, data sent, FPS

Bottom Screen: Settings

• Network configuration (IP/Port) - Press Y to edit
• Camera selection (Inner/Outer)
• 3D checkbox (enabled only for Outer cameras)
• Resolution and quality info

Camera Modes

Mode	Description	3D Support
Inner	Front-facing camera (single lens)	❌ No
Outer	Rear cameras (dual lens)	✅ Yes

Important: The 3D checkbox is only enabled when Outer cameras are selected. The inner camera has only one lens and cannot provide stereo 3D.

Configuration

Method 1: Using Software Keyboard (Recommended)

1. Press Y button in the app
2. Select A to edit IP address or B to edit port
3. Use the 3DS keyboard to enter your PC's IP address
4. Configuration is automatically saved to SD card

Method 2: Manual Config File

Create a config file at SD:/3ds/3ds-webcam-bridge/config.txt:

# Your PC's IP address
ip=192.168.1.100

# Server port
port=9000

The app will load this config on startup. Any changes made via the Y button will update this file.

---

PC Server Options

Full Command-Line Reference

server.py [options]

Options:
  --listen ADDRESS         Listen address (default: 0.0.0.0)
  --port PORT             TCP port (default: 9000)
  --mode MODE             Force mono or auto-detect (default: auto)
  --stereo-mode MODE      Stereo output: off, sbs, anaglyph, dual (default: off)
  --device DEVICE         Virtual camera device
                          Linux: /dev/videoX
                          Windows: "OBS Virtual Camera" or index
  --dual-devices DEVICES  Two devices for dual mode (comma-separated)
  --width WIDTH           Output width per eye (default: 640)
  --height HEIGHT         Output height (default: 480)
  --fps FPS               Output frame rate (default: 15)
  --prefer-backend BACKEND Backend: pyvirtualcam, pyfakewebcam, ffmpeg
  --verbose               Verbose logging

Examples

Linux:

# Basic mono
./run_server.sh --device /dev/video0

# Side-by-side stereo (1280x480 output)
./run_server.sh --stereo-mode sbs --width 640 --height 480

# Anaglyph 3D (red-cyan)
./run_server.sh --stereo-mode anaglyph --width 640 --height 480

# Dual outputs
./run_server.sh --stereo-mode dual --dual-devices /dev/video0,/dev/video1

# Use pyfakewebcam backend
./run_server.sh --prefer-backend pyfakewebcam --device /dev/video0

Windows:

# Basic mono
.\run_server.ps1 -Device "OBS Virtual Camera"

# Side-by-side stereo
.\run_server.ps1 -StereoMode sbs -Width 640 -Height 480

# Dual outputs (requires configuring multiple OBS virtual cameras)
.\run_server.ps1 -StereoMode dual -DualDevices "OBS Virtual Camera,OBS Virtual Camera 2"

---

📁 Project Structure

3ds-webcam-bridge/
├── README.md                   # This file
├── LICENSE                     # MIT license
├── .gitignore
├── examples/
│   └── sample-config.json      # Example configuration
├── 3ds-app/                    # 3DS homebrew application
│   ├── Makefile
│   └── source/
│       ├── main.c              # Main app with UI
│       ├── camera_stream.c     # Camera capture & streaming
│       ├── camera_stream.h
│       └── third_party/
│           └── stb_image_write.h  # JPEG encoder
├── pc-server/                  # PC server (Python)
│   ├── server.py               # Main server application
│   ├── requirements.txt
│   ├── run_server.sh           # Linux launcher
│   └── run_server.ps1          # Windows launcher
├── scripts/                    # Installation & build scripts
│   ├── install-devkitpro.sh    # Install 3DS toolchain (Linux)
│   ├── build-3ds.sh            # Build 3DS app
│   ├── pc-install.sh           # Install PC dependencies (Linux)
│   ├── create-v4l2.sh          # Create v4l2loopback devices (Linux)
│   └── windows/
│       ├── pc-install.ps1      # Install PC dependencies (Windows)
│       └── helpers.psm1        # PowerShell helper functions
├── docs/                       # Documentation
│   ├── design.md               # Technical design details
│   └── troubleshooting.md      # Common issues and solutions
└── dist/                       # Build output
    └── 3ds-webcam-bridge.3dsx

---

📦 Requirements

3DS

• Hardware: Nintendo 3DS/2DS (Old or New) with Homebrew Launcher
• Firmware: Any version with Homebrew access
• SD Card: For installing the .3dsx file
• Wi-Fi: 2.4 GHz network (3DS doesn't support 5 GHz)

PC - Linux

• OS: Ubuntu 20.04+, Debian 11+, or equivalent
• Kernel: 4.4+ with v4l2loopback support
• Python: 3.8+
• Packages:
  • v4l2loopback-dkms
  • v4l2loopback-utils
  • ffmpeg
  • python3-venv

PC - Windows

• OS: Windows 10 (1809+) or Windows 11
• Python: 3.8+ (auto-installed by script)
• OBS Studio: 26.0+ (auto-installed by script)
• winget: For automated installation

Network

• Both devices on same network (LAN/Wi-Fi)
• TCP port 9000 open (configurable)
• Recommended: 5 GHz Wi-Fi for PC (3DS uses 2.4 GHz)

---

🔧 Troubleshooting

Common Issues

"No virtual camera found" (Windows)

• Solution: Start OBS Studio, go to Tools → VirtualCam → Start, then try again
• Ensure OBS Studio 26.0+ is installed (check via winget list OBSProject.OBSStudio)

"/dev/video0: Device or resource busy" (Linux)

• Solution: Close all applications using the device (browser, Zoom, etc.)
• Check: sudo fuser /dev/video0
• Kill processes: sudo fuser -k /dev/video0

"Connection refused" / "Timeout"

• Check that both devices are on the same network
• Verify the server IP address on 3DS matches your PC
• Find your PC IP:
  • Linux: ip addr show or hostname -I
  • Windows: ipconfig (look for IPv4)
• Check firewall:
  • Linux: sudo ufw allow 9000/tcp
  • Windows: Run installer as Administrator to add rule

Low FPS / Laggy stream

• Reduce resolution: --width 320 --height 240
• Lower JPEG quality (edit 3ds-app/source/camera_stream.h, change JPEG_QUALITY)
• Use 5 GHz Wi-Fi for PC (3DS is limited to 2.4 GHz)
• Ensure 3DS is close to Wi-Fi router

"v4l2loopback not loaded" (Linux)

• Solution: Run ./scripts/create-v4l2.sh
• Manual: sudo modprobe v4l2loopback
• Check: lsmod | grep v4l2loopback

Stereo mode not working

• Ensure 3DS is set to Outer cameras with 3D enabled
• Verify server is using --stereo-mode sbs (or anaglyph/dual)
• Check logs with --verbose flag

For more detailed troubleshooting, see docs/troubleshooting.md.

---

📚 Documentation

• design.md: Protocol specification, architecture, performance tuning
• troubleshooting.md: Detailed problem-solving guide
• sample-config.json: Example configuration

External Resources

• devkitPro: https://devkitpro.org/wiki/Getting_Started
• libctru Camera API: https://libctru.devkitpro.org/cam_8h.html
• pyvirtualcam: https://github.com/letmaik/pyvirtualcam
• v4l2loopback: https://github.com/umlaeute/v4l2loopback
• stb_image_write: https://github.com/nothings/stb

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test on both platforms (if possible)
5. Submit a pull request

Ideas for Contributions

• macOS support
• Config UI for IP entry on 3DS
• Recording to file option
• H.264 encoding for lower bandwidth
• Portrait/landscape rotation
• Multiple 3DS clients simultaneously

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Third-Party Libraries

• libctru: https://github.com/devkitPro/libctru (Zlib license)
• stb_image_write: https://github.com/nothings/stb (Public domain / MIT)
• pyvirtualcam: https://github.com/letmaik/pyvirtualcam (GPL-2.0)

---

🙏 Acknowledgments

• devkitPro team for the amazing 3DS toolchain
• stb libraries by Sean Barrett
• v4l2loopback developers
• pyvirtualcam and OBS Studio teams

---

⚡ Performance Tips

3DS Side

• Keep 3DS close to Wi-Fi router
• Close other applications/homebrew
• Use lower resolution if needed (edit source)

PC Side

• Use wired Ethernet for PC (3DS will be on Wi-Fi)
• Close unnecessary applications
• For dual mode, ensure both v4l2 devices are created

Network

• Use QoS to prioritize 3DS traffic if possible
• Avoid network congestion (large downloads, streaming)

---

Made with ❤️ for the 3DS homebrew community