Skip to content
Klutch.sh Docs

Deploying NymphCast

Introduction

NymphCast is a software solution for turning a system into an audio and video receiver, similar to Google Chromecast but with full control and no proprietary software. It allows you to cast audio, video, and images from a variety of sources to any system running the NymphCast server.

Built with C++, NymphCast provides low-latency streaming with support for a wide range of media formats. The modular architecture allows it to run on everything from Raspberry Pi devices to full desktop systems.

Key highlights of NymphCast:

  • Open Protocol: No proprietary software or cloud dependencies
  • Multi-Format Support: Plays most audio and video formats via FFmpeg
  • Low Latency: Optimized for real-time streaming
  • Cross-Platform: Server runs on Linux, Windows, and macOS
  • Client Options: Desktop and mobile clients available
  • URL Streaming: Cast media from URLs directly
  • Screen Mirroring: Cast entire desktop screens
  • Media Apps: Integration with media server applications
  • Extensible: Support for custom applications and extensions
  • Open Source: BSD-3 licensed with active development

This guide walks through deploying NymphCast Server on Klutch.sh using Docker.

Why Deploy NymphCast on Klutch.sh

Deploying NymphCast on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the build and deployment process.

Persistent Storage: Attach persistent volumes for configuration and cache.

HTTPS by Default: Automatic SSL certificates for secure access.

GitHub Integration: Version-controlled deployments through your repository.

Scalable Resources: Allocate CPU and memory based on streaming needs.

Environment Variable Management: Configure your server securely.

Custom Domains: Use your own domain for your casting server.

Always-On Availability: Your casting server remains accessible 24/7.

Prerequisites

Before deploying NymphCast on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Understanding of media streaming concepts
  • A NymphCast client application for testing
  • (Optional) A custom domain for your NymphCast instance

Understanding NymphCast Architecture

NymphCast consists of several components:

NymphCast Server: The core receiver application that accepts incoming streams and handles playback.

NymphCast Client: Desktop and mobile applications for sending media to servers.

NymphRPC: The communication protocol used between client and server.

FFmpeg Backend: Handles media decoding for broad format support.

SDL2: Manages audio and video output on the server side.

Deploying NymphCast on Klutch.sh

    Create Your GitHub Repository

    Create a new GitHub repository for your NymphCast deployment configuration.

    Create the Dockerfile

    Create a Dockerfile in your repository root:

    FROM debian:bullseye-slim
    

    # Install dependencies
    RUN apt-get update && apt-get install -y \
        build-essential \
        git \
        cmake \
        pkg-config \
        libsdl2-dev \
        libsdl2-image-dev \
        libfreeimage-dev \
        libfreetype6-dev \
        libcurl4-openssl-dev \
        libavcodec-dev \
        libavformat-dev \
        libavutil-dev \
        libswscale-dev \
        libswresample-dev \
        libasound2-dev \
        libpoco-dev \
        && rm -rf /var/lib/apt/lists/*
    

    # Clone and build NymphCast
    WORKDIR /opt
    RUN git clone --recursive https://github.com/MayaPosch/NymphCast.git && \
        cd NymphCast/src/server && \
        make -j$(nproc)
    

    # Set up server directory
    WORKDIR /opt/NymphCast/src/server
    

    # Expose NymphCast port
    EXPOSE 4004
    

    CMD ["./bin/nymphcast_server"]

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project.

    Create a New App

    Within your project, create a new app and connect your GitHub repository.

    Configure TCP Traffic

    In the deployment settings:

    • Select TCP as the traffic type (NymphCast uses its own protocol)
    • Set the internal port to 4004

    Set Environment Variables

    Configure any needed environment variables:

    VariableValue
    DISPLAY:0 (if using display output)
    NYMPHCAST_CONFIG/config/nymphcast.ini

    Attach Persistent Volumes

    Add persistent storage:

    Mount PathRecommended SizePurpose
    /config1 GBConfiguration files
    /cache10 GBMedia cache

    Deploy Your Application

    Click Deploy to start the build process.

    Test with NymphCast Client

    Once deployed, connect using a NymphCast client:

    1. Download NymphCast Player
    2. Configure server address
    3. Test media casting

Configuration

Server Configuration

Create a configuration file at /config/nymphcast.ini:

[server]
name = My NymphCast Server
port = 4004


[audio]
disable = false
device = default


[video]
disable = false

Audio Configuration

Configure audio output:

  • Set audio device based on your hardware
  • Configure volume levels
  • Enable/disable audio output

Video Configuration

Configure video output:

  • Set display resolution
  • Configure scaling options
  • Enable/disable video output

Using NymphCast

Casting Media Files

From the NymphCast Player:

  1. Open NymphCast Player
  2. Connect to your server
  3. Add media files to the playlist
  4. Click Play to start casting

URL Streaming

Cast media from URLs:

  1. Use the “Add URL” option
  2. Enter the media URL
  3. The server fetches and plays the content

Screen Casting

Cast your desktop:

  1. Select “Screen Cast” option
  2. Choose screen or window
  3. Start streaming

Supported Formats

NymphCast supports formats handled by FFmpeg:

Video: MP4, MKV, AVI, WebM, MOV, FLV, and more Audio: MP3, FLAC, OGG, WAV, AAC, and more Containers: Most common container formats Codecs: H.264, H.265, VP9, AAC, MP3, and more

Production Best Practices

Performance Optimization

  • Allocate sufficient CPU for transcoding
  • Use hardware acceleration if available
  • Cache frequently accessed media
  • Optimize network settings

Security Recommendations

  • Limit access to trusted networks
  • Use firewall rules appropriately
  • Keep software updated
  • Monitor for unauthorized access

Network Configuration

  • Ensure stable network connection
  • Configure appropriate buffer sizes
  • Optimize for latency or quality
  • Consider bandwidth limitations

Troubleshooting Common Issues

Client Cannot Connect

  • Verify server is running
  • Check port configuration
  • Confirm network connectivity
  • Review firewall rules

Media Won’t Play

  • Check format compatibility
  • Verify codec support
  • Review error logs
  • Test with different media

Audio/Video Sync Issues

  • Adjust buffer settings
  • Check network latency
  • Optimize server resources
  • Try different media settings

Additional Resources

Conclusion

Deploying NymphCast on Klutch.sh provides an open-source, privacy-respecting alternative to proprietary casting solutions. With support for a wide range of media formats and cross-platform compatibility, NymphCast offers flexible media streaming without vendor lock-in or cloud dependencies.