Releases ship Debian .deb packages, a macOS .pkg installer, and a Homebrew formula (scastd.rb). SHA256 checksums for all artifacts are provided in CHECKSUMS.txt. Verify package integrity before installation:
sha256sum -c CHECKSUMS.txtmacOS users can run:
shasum -a 256 -c CHECKSUMS.txtSCASTD (Statistical Casting Daemon) is a lightweight, high-performance statistics collection and analytics engine we designed specifically for streaming media infrastructure. Unlike traditional streaming servers, we built SCASTD to be the definitive monitoring solution that bridges legacy and modern streaming protocols, providing unified analytics across your entire streaming ecosystem.
As DevSecOps professionals with over 20 years of combined experience in streaming media infrastructure, we consistently encountered the challenge of collecting unified statistics from diverse streaming server implementations. Traditional monitoring tools either focused on single protocols or provided basic metrics without the depth needed for professional streaming operations. That's why we created SCASTD - to provide:
/*
* scastd_core.h - Statistical Collection Engine Architecture
* Authors: oddsock, dstjohn (David St. John)
* Created: Project inception
* Purpose: We designed this daemon to efficiently collect statistics from multiple
* streaming protocols and provide unified analytics through modern APIs
*
* Key Design Principles We Implemented:
* - Protocol-agnostic statistics collection
* - Real-time data aggregation and analysis
* - Modern RESTful API with JSON/XML output
* - Multi-database backend support for scalability
* - Enterprise-grade logging and monitoring
* - Security-first approach with authentication
*/
// We structured the daemon with these core capabilities:
typedef struct {
char* target_servers[]; // We monitor multiple server types simultaneously
int polling_intervals[]; // We configure collection frequency per server
database_config_t backends; // We support multiple database backends
api_config_t rest_api; // We serve statistics via modern HTTP APIs
logging_config_t logging; // We provide comprehensive operational logging
security_config_t auth; // We implement token-based authentication
} scastd_engine_t;
Based on our decades of experience with streaming infrastructure, we engineered SCASTD with these distinguishing characteristics that set it apart from traditional monitoring solutions:
Protocol Unification: We implement native support for SHOUTcast v1/v2, Icecast2, and legacy ICY protocols, providing a single interface to monitor heterogeneous streaming environments. This eliminates the need for multiple monitoring tools and provides consistent metrics across different server types.
Real-time Analytics Engine: We built a sophisticated statistics aggregation system that not only collects current metrics but also performs historical analysis, trend detection, and predictive analytics. This gives streaming operators the insights they need to optimize performance and plan capacity.
Enterprise Integration Ready: We designed SCASTD with modern DevOps practices in mind, providing native integration with Prometheus, Grafana, ELK stack, and other monitoring platforms. The RESTful API design ensures seamless integration with existing infrastructure monitoring systems.
Scalable Architecture: We implemented a multi-threaded collection engine with configurable polling intervals and database connection pooling, allowing SCASTD to monitor hundreds of streaming servers while maintaining low resource consumption.
Before diving into installation, it's important to understand how we structure our development process. We maintain three distinct branches that serve different purposes in our engineering pipeline:
masterBranch: Our production-ready code that undergoes our ProductionBuildDeployment pipelinedevBranch: Our active development branch running the DevelopmentBuildPipeline for integration testingfutureBranch: Our experimental features branch using the FutureBuildPipeline for cutting-edge development
This three-tier approach allows us to maintain stability in production while continuously innovating and testing new features.
Before building SCASTD, we suggest ensuring your system has the necessary development tools and libraries. Based on our experience across different platforms, here's what you'll need:
📦 Debian/Ubuntu Installation
# install_dependencies_debian.sh - Debian/Ubuntu dependency installation
# Authors: SCASTD Development Team
# Purpose: We streamline the build process on Debian-based systems
#!/bin/bash
# We always start with system updates to ensure package compatibility
sudo apt-get update && sudo apt-get install -y \
build-essential \
autoconf \
automake \
libtool \
pkg-config \
libxml2-dev \
libcurl4-openssl-dev \
libmysqlclient-dev \
libpq-dev \
libmicrohttpd-dev \
libssl-dev \
libyaml-dev
echo "✅ All dependencies installed successfully"
echo "🚀 Ready to build SCASTD"🍎 macOS arm64 Installation
# install_dependencies_macos.sh - macOS dependency installation
# Authors: SCASTD Development Team
# Purpose: We optimize this for Apple Silicon Macs based on our development experience
#!/bin/bash
# We use Homebrew for consistent package management on macOS
brew update
brew install autoconf automake libtool pkg-config libxml2 curl mysql-client libpq libmicrohttpd libyaml
# We set PKG_CONFIG_PATH so the build system can locate all libraries
export PKG_CONFIG_PATH="/opt/homebrew/opt/libpq/lib/pkgconfig:/opt/homebrew/opt/mysql-client/lib/pkgconfig:/opt/homebrew/opt/libxml2/lib/pkgconfig:$PKG_CONFIG_PATH"
echo "✅ macOS dependencies installed"
echo "📝 PKG_CONFIG_PATH configured for build"We designed our build process to be straightforward while maintaining professional standards. Here's how to compile SCASTD from source:
# build_scastd.sh - Complete build script
# Authors: SCASTD Development Team
# Purpose: We provide this comprehensive build script for reliable compilation
#!/bin/bash
set -e # We enable strict error handling
echo "🔧 Generating build system files..."
# We generate the configure script and Makefiles using autotools
./autogen.sh
echo "🔍 Configuring build with optimizations..."
# We configure with C++17 support and optimization flags
./configure CXXFLAGS='-std=c++17 -g -O2 -Wall -Werror'
echo "⚡ Building SCASTD..."
# We use parallel compilation to speed up the build process
make -j$(nproc)
echo "🧪 Running test suite..."
# We always run tests to ensure build quality
make check
echo "✅ Build completed successfully!"
echo "📍 Binary location: ./src/scastd"sudo dpkg -i scastd_<version>_amd64.deb
sudo apt-get install -fsudo installer -pkg scastd-<version>.pkg -target /Release archives include a scastd.rb Homebrew formula. To test it locally:
brew install --formula ./scastd.rb
brew services start scastdOnce verified, install from the official tap:
brew tap davestj/scastd
brew install scastdTo update the formula later:
brew upgrade scastdTo remove it:
brew uninstall scastdFor details on creating the macOS package or Homebrew formula yourself, see packaging/macos/README.md.
- Debian/Ubuntu:
sudo nano /etc/scastd/scastd.conf - macOS (.pkg):
sudo nano /usr/local/etc/scastd.conf - macOS (Homebrew):
nano /opt/homebrew/etc/scastd.conf
Update absolute paths for databases and certificates as needed.
- Debian/Ubuntu
sudo systemctl enable scastd
sudo systemctl start scastd- macOS (Homebrew)
brew services start scastd- macOS (.pkg)
sudo launchctl load -w /Library/LaunchDaemons/com.scastd.plistConfirm the daemon responds:
curl http://localhost:8000/v1/status.json
curl http://localhost:8000/v1/status.xmlExpected responses:
{"status":"ok"}<status>ok</status>Troubleshooting tips if unreachable:
- Check service state:
sudo systemctl status scastdorbrew services list - Ensure the configured port matches the
curlcommand - Verify no firewall or other service blocks the port
- Review logs in
/var/log/scastdor withjournalctl -u scastd
scastd --helpUsage: scastd [options]
-h, --help Show this help and exit
-c, --config PATH Configuration file
-D, --daemon Run as a daemon
--pid-file PATH PID file path (used with --daemon)
--ip ADDRESS Bind IP address
--port PORT HTTP server port
--debug LEVEL Debug level
--poll INTERVAL Poll interval (e.g., 60s, 5m)
--test-mode Validate configuration and exit
--db-host HOST Database host
--db-port PORT Database port
--db-name NAME Database name
--db-user USER Database user
--db-pass PASS Database password
--sqlite-db PATH SQLite database file
--setupdb TYPE Initialize database of specified type
--ssl-cert PATH SSL certificate file
--ssl-key PATH SSL key file
--ssl-enable Enable SSL
--dump Dump database and exit
--dump-dir DIR Directory for database dump
Run with certificate options:
scastd --ssl-enable \
--ssl-cert /etc/letsencrypt/live/example.com/fullchain.pem \
--ssl-key /etc/letsencrypt/live/example.com/privkey.pemOr configure scastd.conf:
ssl_enable true
ssl_cert /etc/letsencrypt/live/example.com/fullchain.pem
ssl_key /etc/letsencrypt/live/example.com/privkey.pem
On macOS the Homebrew prefix contains the certificates:
ssl_enable true
ssl_cert /usr/local/etc/letsencrypt/live/example.com/fullchain.pem
ssl_key /usr/local/etc/letsencrypt/live/example.com/privkey.pem
# Use /opt/homebrew on Apple Silicon
curl http://localhost:8000/v1/status.json
curl http://localhost:8000/v1/status.xml
curl http://localhost:8000/v1/uptime
curl -k https://localhost:8000/v1/status.json
curl https://example.com:8000/v1/status.jsonDebian/Ubuntu
sudo certbot certonly --standalone -d example.commacOS (Homebrew)
brew install certbot
sudo certbot certonly --standalone -d example.comCertificates are placed under the Let's Encrypt directory for your platform:
| Platform | Certificate path |
|---|---|
| Debian/Ubuntu | /etc/letsencrypt/live/example.com/ |
| macOS (Intel) | /usr/local/etc/letsencrypt/live/example.com/ |
| macOS (Apple Silicon) | /opt/homebrew/etc/letsencrypt/live/example.com/ |
Reference fullchain.pem and privkey.pem from that directory in
scastd.conf and restart the daemon:
sudo systemctl restart scastd # or reload
brew services restart scastd # macOSWe designed SCASTD's configuration system to be both powerful and intuitive. The daemon supports multiple configuration methods to accommodate different deployment scenarios and security requirements.
SCASTD reads settings from configuration files that support environment variable overrides - a pattern we've found essential in containerized and cloud-native environments:
- scastd.conf - Main configuration file with comprehensive settings
- scastd_pg.conf - PostgreSQL-specific configuration example
Console logging is enabled by default when SCASTD runs in the foreground. Running with --daemon disables console output unless log_console true is set in the configuration. Set log_console false to silence console logs even in foreground mode.
We implement robust environment variable support for sensitive data and containerized deployments:
# Environment variables we recognize for secure configuration
export SCASTD_USERNAME="statistics_user"
export SCASTD_PASSWORD_FILE="/run/secrets/db_password"
export SCASTD_DATABASE_HOST="mysql-cluster.internal"
export SCASTD_API_TOKEN_SECRET="your-jwt-secret-here"
export ICEADMINUSER="admin"
export ICEUSERPASS="hackme"These credentials configure access to the Icecast administrative interface. If
ICEADMINUSER or ICEUSERPASS are not provided, the daemon falls back to the
legacy SCASTD_ADMINUSER and SCASTD_USERPASS variables.
For detailed configuration instructions, please refer to our comprehensive Installation Guide.
We designed SCASTD's HTTP API following RESTful principles with comprehensive authentication and rate limiting. The API serves statistics on port 8333 by default, with versioned endpoints to ensure backward compatibility.
Our API offers several categories of endpoints designed for different use cases:
Statistics Collection Endpoints: Access real-time and historical streaming server metrics Health Monitoring Endpoints: Check daemon status and perform health verification Configuration Endpoints: Manage monitored servers and collection settings Export Endpoints: Generate reports in various formats (JSON, XML, CSV)
We provide ready-to-use integration examples for popular monitoring platforms:
- Prometheus Integration: Native metrics export for Prometheus scraping
- Grafana Dashboards: Pre-built dashboards for streaming analytics
- ELK Stack Integration: Structured logging for Elasticsearch ingestion
- Custom API Clients: Example implementations in Python, PHP, and Node.js
For complete API documentation and integration examples, see our API Documentation.
We implement comprehensive testing to ensure SCASTD's reliability across different environments and use cases. Our testing strategy covers multiple layers from unit tests to full integration scenarios.
Unit Tests: We test individual components and functions in isolation
Integration Tests: We verify correct interaction between system components
Protocol Tests: We validate compatibility with different streaming server types
Performance Tests: We benchmark performance under various load conditions
Security Tests: We verify authentication, authorization, and data protection
# We provide a comprehensive testing framework
make check # Run all unit tests
./tests/integration_tests.sh # Run integration test suite
./tests/performance_tests.sh # Run performance benchmarks
./tests/security_tests.sh # Run security validation tests
We maintain comprehensive documentation to support different user needs and experience levels. Our documentation is organized into practical guides that build understanding progressively.
| Document | Purpose | Audience |
|---|---|---|
| Installation Guide | Step-by-step setup instructions for all platforms | System Administrators |
| Contributing Guide | Development workflow and coding standards | Developers |
| Change Log | Version history and feature updates | All Users |
| License Information | Legal terms and GPL v2.0 details | All Users |
| Authors & Credits | Project contributors and acknowledgments | Community |
| Release Notes | Latest updates and announcements | All Users |
| Document | Purpose | Audience |
|---|---|---|
| Continuous Integration | Build pipeline and automation details | DevOps Engineers |
| CI Secrets Management | Secure credential handling in pipelines | DevOps Engineers |
| Database Migration | Database setup and migration procedures | Database Administrators |
| PostgreSQL Configuration | PostgreSQL-specific setup and tuning | Database Administrators |
| HTTPS Configuration | SSL/TLS setup and certificate management | System Administrators |
| Logging Configuration | Log management and analysis setup | Operations Teams |
| Resource Limits | Performance tuning and resource management | System Administrators |
| Packaging Guide | Distribution and deployment packaging | Release Engineers |
| Icecast2 Integration | Specific Icecast2 monitoring setup | Streaming Engineers |
| File | Purpose | Environment |
|---|---|---|
| scastd.conf | Main configuration template | Production/Development |
| scastd_pg.conf | PostgreSQL-specific configuration | PostgreSQL Environments |
| scastd.service | Systemd service configuration | Linux Systems |
| Agent Configuration | Build agent and automation setup | CI/CD Systems |
We welcome contributions from the streaming media and DevOps communities. Having maintained open source projects for over two decades, we believe in fostering collaborative development while maintaining high code quality standards.
Our contribution process follows established DevSecOps best practices:
- Fork & Branch: We suggest forking the repository and working in feature branches based on our three-tier system
- Code Standards: We require adherence to our coding standards outlined in CONTRIBUTING.md
- Testing Requirements: We expect all contributions to include appropriate tests and documentation
- Security Review: We mandate security review for all code changes affecting authentication or data handling
- Documentation Updates: We require documentation updates for new features and API changes
We actively seek contributions in these key areas:
- Protocol Extensions: Expanding compatibility with additional streaming protocols and metadata formats
- Monitoring Integrations: New exporters for monitoring systems like DataDog, New Relic, and CloudWatch
- Database Backends: Additional database driver implementations and optimization
- Performance Optimization: Improving collection efficiency and reducing resource consumption
- Documentation: User guides, tutorials, and deployment examples for different environments
- Testing: Expanding test coverage and adding performance benchmarks
We provide several deployment options to accommodate different infrastructure requirements:
Containerized Deployment: Docker and Kubernetes configurations for cloud-native environments Traditional Installation: System packages and service configurations for bare-metal deployments Cloud Integration: Native integration examples for AWS, Azure, and Google Cloud Platform
As a monitoring tool, SCASTD includes comprehensive self-monitoring capabilities:
- Health Endpoints: Built-in health checks for load balancers and monitoring systems
- Metrics Export: Prometheus-compatible metrics about SCASTD's own performance
- Audit Logging: Detailed logging of all API access and configuration changes
- Performance Monitoring: Real-time visibility into collection performance and resource usage
For deployment guides and operational procedures, see our Installation Guide and Logging Documentation.
We provide support through multiple channels based on your needs:
We maintain several community resources to support SCASTD users and contributors:
- GitHub Discussions: Community Q&A, feature requests, and general discussion
- Project Wiki: Extended documentation, tutorials, and community-contributed guides
- Issue Tracking: Bug reports, feature requests, and development coordination
- Release Notifications: Automated notifications for new releases and security updates
This project is licensed under the GNU General Public License v2.0. We chose this license to ensure SCASTD remains open source and benefits the entire streaming media community while protecting contributors' rights and maintaining compatibility with enterprise environments.
Copyright (C) 2025 oddsock, David St. John (dstjohn)
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
For complete license terms, see LICENSE.md and COPYING.md.
We focus on core functionality and stability in our current release:
- ✅ Multi-protocol statistics collection (SHOUTcast v1/v2, Icecast2, ICY)
- ✅ RESTful API with JSON/XML output formats
- ✅ Multi-database backend support (MySQL, MariaDB, PostgreSQL, SQLite)
- ✅ Comprehensive logging and monitoring capabilities
- ✅ JWT-based authentication and security features
Our next release will focus on enhanced analytics and integration:
- 🔧 Real-time WebSocket streaming of statistics
- 🔧 Advanced analytics engine with trend analysis
- 🔧 Native Prometheus metrics export
- 🔧 Enhanced ICY2 protocol support
- 🔧 Grafana dashboard templates
Our long-term roadmap includes advanced features for enterprise deployments:
- 📋 Machine learning-based anomaly detection
- 📋 Multi-tenant support for service providers
- 📋 Advanced reporting and alerting capabilities
- 📋 Cloud-native scaling and orchestration
- 📋 Enhanced security features and compliance tools
Created by oddsock & David St. John | DevSecOps Professionals | 20+ Years Streaming Infrastructure Experience