A Node.js library for converting RTSP streams to MJPEG for web browser viewing with minimal latency.
- Low-Latency Streaming: Optimized for minimal delay using WebSocket transport
- Robust Error Handling: Automatic reconnection and comprehensive error reporting
- Responsive UI: Modern interface with loading states and error feedback
- Multiple Resolution Support: 320x240 to 1920x1080 (configurable)
- Transport Protocol Options: TCP or UDP
- Quality Control: Adjustable compression quality (1-31, lower is better)
- Frame Rate Control: Configurable target FPS
- Performance Monitoring: Real-time statistics and health checks
- Multiple Client Support: Efficient handling of multiple viewers
- TypeScript Support: Full type definitions included
- Node.js (v14.0.0 or higher)
- FFmpeg must be installed and available in your PATH
brew install ffmpegsudo apt-get update
sudo apt-get install ffmpeg- Download from ffmpeg.org
- Extract the files
- Add the bin folder to your system PATH
npm install rtsp-stream-viewerconst RTSPStreamServer = require('rtsp-stream-viewer');
const server = new RTSPStreamServer({
rtspUrl: 'rtsp://your-camera-url:554/stream',
port: 3000
});
server.start()
.then(() => console.log('Server running on http://localhost:3000'))
.catch(console.error);<!DOCTYPE html>
<html>
<head>
<title>RTSP Stream Viewer</title>
<link rel="stylesheet" href="/rtsp-player.css">
</head>
<body>
<div id="player-container"></div>
<script src="/socket.io/socket.io.js"></script>
<script src="/rtsp-player.js"></script>
<script>
const player = new RTSPPlayer({
container: '#player-container',
autoConnect: true
});
</script>
</body>
</html>const defaultConfig = {
rtspUrl: 'rtsp://your-camera-url:554/stream',
transport: 'udp', // 'tcp' or 'udp'
frameRate: 15, // Default frame rate
resolution: '640x360', // Default resolution
quality: 3, // JPEG quality (1-31, lower is better)
port: 3000, // Server port
ffmpegOptions: [ // Advanced FFmpeg options
'-fflags', 'nobuffer',
'-flags', 'low_delay'
]
};const streamSettings = {
maxQueueSize: 3, // Maximum frames to buffer per client
maxClientsPerFrame: 10, // Process clients in batches
statsResetInterval: 10000 // Reset frame counters every 10 seconds
};interface RTSPConfig {
rtspUrl: string; // RTSP stream URL
transport: 'tcp' | 'udp'; // Transport protocol
frameRate: number; // Target frame rate (1-60)
resolution: string; // Video resolution (e.g., '640x360')
quality: number; // JPEG quality (1-31, lower is better)
port: number; // Server port
ffmpegOptions: string[]; // Additional FFmpeg options
}interface StreamStats {
activeClients: number; // Number of connected clients
frameCount: number; // Frames processed since last reset
totalFrames: number; // Total frames processed
currentFps: number; // Current frames per second
uptime: number; // Stream uptime in seconds
isActive: boolean; // Stream active status
config: RTSPConfig; // Current configuration
skippedFrames: number; // Frames skipped due to processing backlog
}- `GET /api/config` - Get current configuration
- `POST /api/config` - Update configuration
- `POST /api/config/reset` - Reset to default configuration
- `GET /api/stats` - Get stream statistics
- `GET /health` - Server health check
- Status messages with error states
- Connection status indicator
- Stream statistics display
The player provides customizable CSS classes:
.rtsp-player-stream-wrapper // Stream container
.rtsp-player-canvas // Video canvas
.rtsp-player-status // Status message overlay
.rtsp-player-spinner // Loading spinner
.rtsp-player-status-content // Status message content
.rtsp-player-status.error // Error state styling// Emitted Events
socket.emit('update-config', newConfig); // Update stream configuration
socket.emit('stream-reconnect'); // Request stream reconnection
// Received Events
socket.on('stream', (data) => {}); // Receive frame data
socket.on('stream-error', (data) => {}); // Stream error occurred
socket.on('stream-status', (data) => {}); // Stream status update
socket.on('config', (config) => {}); // Configuration updated- Batch processing for multiple clients
- Frame queue management per client
- Frame skipping for processing backlog prevention
- Double buffering for tear-free rendering
- Automatic stream reconnection
- Graduated reconnection delays (2-10 seconds)
- Error-specific status messages
- Stream health monitoring
- Last valid frame caching for stable display
// Stream Statistics
const stats = await player.getStats();
{
activeClients, // Current connected clients
frameCount, // Frames since last reset
totalFrames, // Total processed frames
currentFps, // Current FPS
uptime, // Stream uptime
isActive, // Stream active status
config, // Current configuration
skippedFrames // Frames skipped due to processing backlog
}- Frame queue size limits
- Batch processing to prevent memory spikes
- Automatic cleanup of disconnected clients
- Frame processing lock to prevent backlog
- Streamlined configuration panel with auto-close on apply
- Simplified controls for better user experience
- Responsive design for various screen sizes
- Real-time status indicators
// Stream Errors
'Failed to connect to RTSP stream: Connection refused'
'Invalid RTSP stream URL or stream not accessible'
'Stream connection timed out'
'Failed to restart stream'
'Stream error occurred'
// Configuration Errors
'Failed to update stream configuration'
'Failed to reset configuration'// Connection States
'connecting' // Initial connection attempt
'connected' // Successfully connected
'disconnected' // Connection lost
'error' // Error state
// Error Messages
'Stream not responding. Attempting to reconnect...'
'Connection timeout. Retrying...'
'Connection refused. Retrying...'
'Failed to connect to stream. Retrying...'
'Stream stopped. Attempting to reconnect...'-
Memory Usage
- Monitor frame queue sizes
- Use batch processing for multiple clients
- Implement automatic cleanup
-
Network Optimization
- Use appropriate transport protocol
- Adjust frame rate based on network
- Monitor skipped frames
- Implement reconnection strategy
- Frame validation to prevent rendering corrupted data
-
Client Management
- Limit maximum concurrent clients
- Process clients in batches
- Clean up disconnected clients
- Monitor client performance
-
Black Screen
- Check RTSP URL accessibility
- Verify FFmpeg installation
- Check network connectivity
- Try switching transport protocol (TCP/UDP)
-
High Latency
- Reduce resolution
- Lower frame rate
- Adjust quality setting
- Check network conditions
-
Connection Issues
- Verify RTSP server is running
- Check firewall settings
- Ensure correct port configuration
- Verify network permissions
-
Performance Issues
- Reduce number of concurrent clients
- Lower resolution or frame rate
- Adjust buffer settings
- Monitor server resources
-
RTSP Authentication
- Use authenticated RTSP URLs
- Implement token-based authentication
- Secure credentials storage
-
Network Security
- Use HTTPS for web interface
- Implement WebSocket security
- Configure CORS appropriately
- Rate limit connections
This project is licensed under the MIT License - see the LICENSE file for details.
- FFmpeg for video processing
- Socket.IO for WebSocket implementation
- Express.js for HTTP server
- Node.js community for support and packages