MMM-RTSPStream - Video Streaming from Live Feeds (Security Cameras)

This is a module for the MagicMirror².

This module will show a live RTSP video stream and/or periodic snapshots on the Magic Mirror from any IP Security Camera which supports the RTSP protocol and/or can serve a snapshot periodically.

:warning: This module is no longer being actively developed. I will accept PRs and leave the repo active, but will not be directly supporting any issues. If anyone is interested in assuming ownership of the module, please contact @shbatm. :warning:

Why?

• I am no longer using this module on my own mirror. After several years, I found that I use the snapshots much more frequently than I streamed the actual cameras, which can be performed by much simpler modules and methods. To enable streaming, WebRTC (like MMM-HomeAssistant-WebRTC) is a newer and better standard with much lower server overhead and latency for delivering RTSP Streams to the frontend than any of the options used here, in the future, this will be the method I focus on and I will not try to shoehorn another technology into this module.
• Update 5-Oct-2022: See alternative module MMM-RTSPtoWeb for a drastically simplified module relying on WebRTC and a backend server.

Features:

• Supports single or multiple camera streams/snapshots
• For multiple streams: supports rotating through streams in a single window or displaying multiple windows (with customizeable layout)
• Supports fetching snapshots from a file or url when not actively streaming
• Flexible configurations to limit resource use on Raspberry Pi --
  • Stops all streams when module is hidden
  • Option for AutoPlay or manual starting of stream
  • Plays one or all streams (when displaying multiple)
  • Note: 3 simultaneous streams on a RaspberryPi 3 is about the limit for usability.
• Support for MMM-KeyBindings module for Play/Pause Remote Control and navigation of multiple streams
• Hardware-Accelerated Playback on the main screen, with option to use software playback on a remote browser window.
• When using omxplayer or vlc, double-clicking the play button (or longpressing PlayPause key if using MMM-KeyBindings) will play the video fullscreen. Click anywhere once (or Pause with MMM-KeyBindings) to exit.

Dependencies:

• The following packages are required for the module to function fully and the installer will attempt to install them with apt:
  • ffmpeg, omxplayer, vlc, devilspie2, wmctrl
• For hardware-accelerated streaming, vlc or omxplayer is required.
• For manipulating VLC's windows, devilspie2 and wmctrl are used.
• For software-decoded streaming and/or remote browser viewing:
  • Requires jsmpeg for front-end display of stream.
  • Requires node-rtsp-stream-es6 Node.js module and ffmpeg for backend.
  • Video flow using 'ffmpeg': Camera RTSP Stream → ffmpeg pre-processor → MM module's node_helper.js (via node-rtsp-stream-es6) → Web Socket (ws) → MagicMirror² (via jsmpeg)

Screenshot:

Installation:

Quick install

If you followed the default installation instructions for the Magic Mirror² project, you should be able to use the automatic installer. The following command will download the installer and execute it:

bash -c "$(curl -s https://raw.githubusercontent.com/shbatm/MMM-RTSPStream/master/scripts/installer.sh)"

Updating after a Module Update:

Re-run the installation script above, or do the following:

cd ~/MagicMirror/modules/MMM-RTSPStream
git pull
npm install

Using the module

To use this module, use the configuration builder tool included.

1. Install the module (see above).
2. Add the following to your config:

   {
       module: 'MMM-RTSPStream',
       position: 'middle_center',
       config: {
           initialSetup: true,
       }
   }

3. Open a web-browser and navigate to: http://your-mirror-ip:8080/MMM-RTSPStream/config.html
4. Use the tool to generate your config details.
5. Copy the section you your MagicMirror config.js file.
6. Restart the MagicMirror

Configuration options

It is highly recommended you use the tool included. Several sample configurations are available on this wiki page, detailed options are listed below.

Stream Configuration Options

Each stream you would like to show should be added to the the configuration by adding a streamX section, where X is the number of the stream (e.g. stream1, stream2, stream3, etc.)

config: {
    // ... <other config options; see above> ...,
    stream1: {
        name: 'BigBuckBunny Test Stream',
        url: 'rtsp://184.72.239.149/vod/mp4:BigBuckBunny_115k.mov',
        // ... <additional stream options; see below> ...
    },
    stream2: {
        // ...
    },
    // ...
}

Testing a camera feed

To test to make sure you have a working url for a camera feed: create a text file with the URL as the first and only line in the file. Save the file as <somename>.strm and open the file with a video player like VLC.

Advanced Stream Configurations

This module has been tested exclusively with streams for Hikvision (Swann) cameras. You may find that you need to adjust the ffmpeg settings that are used beyond just frame rate and size. The command line arguements for ffmpeg can be changed by editing Line 14 of the following file after install. The ffmpeg arguement list is passed as an array.

~/MagicMirror/modules/MMM-RTSPStream/node_modules/node-rtsp-stream-es6/src/mpeg1muxer.js

Controlling from other modules

The streams can be controlled on the main screen by sending a module notification. Examples:

this.sendNotification("RTSP-PLAY", "all"); // Play all streams (or current stream if rotating)
this.sendNotification("RTSP-PLAY", "streamX"); // Play a particular stream (when not rotating)
this.sendNotification("RTSP-PLAY-FULLSCREEN", "streamX"); // Play a particular stream fullscreen (when using OMXPLAYER)
this.sendNotification("RTSP-PLAY-WINDOW", { name:"streamX", box: { top: XX, right: XX, bottom: XX, left: XX } }); // Play a particular stream in a custom window (when using OMXPLAYER)
this.sendNotification("RTSP-STOP", "all"); // Stop the streams
this.sendNotification("RTSP-STOP", "streamX"); // Stop a particular stream

KeyBindings Configuration (Requires MMM-KeyBindings)

To change from the defaults, add changes to the end of the module's configuration section

keyBindings: {
    enabled: true,
    mode: "DEFAULT",
    map: {
        Play: "MediaPlayPause",
        Previous: "MediaPreviousTrack",
        Next: "MediaNextTrack",
    }
}

To-do

• Add better touchscreen support (use an OnTouch method to play/pause instead of OnClick).
• KNOWN ISSUE: snapshots can be stopped by another "instance" of the mirror running in a different window. Expected behavior: should only affect the local window.
• KNOWN ISSUE: omxplayer will only play a certain maximum number of streams at a time. On a RPi3, this appears to be a max of 3. It won't error, it just won't play another stream. To fix: adjust the memory split of the GPU/CPU using the raspi-config command.

Experimentation

This section includes some untested options and configurations that may be useful in the future.

Use ffmpeg to capture snapshots from an RTSP Stream

// Grab a frame every x seconds and save as thumb.png:
ffmpeg -i {RTSP_SOURCE} -f image2 -vf fps=fps=1/{x} -update 1 thumb.png

// Grab the first frame from a stream and save as thumb.jpg
ffmpeg -i {RTSP_SOURCE} -ss 00:00:01.500 -f image2 -vframes 1 thumb.png

(source)