Videos

Devices can add support for streaming video, which can be viewed from the mobile app & dashboards.

Videos are available on Homey Pro (Early 2023) and Homey Pro mini since v12.7.0, and Homey Cloud.

Your app's devices can let Homey know that they support a video stream. Once a front-end (e.g. the Homey app for iOS & Android) requests to start watching, your app will receive a request to share the stream's details, such as URL and authentication. The app, nor Homey, does any transcoding, but acts as a broker between the camera and the front-end.

Supported Video Types

Homey supports video streams with WebRTC, RTSP, RTMP, HLS, DASH. Other types may be supported. Because the Homey Mobile App embeds a VLC media player, you can always try to see if your video type works.

Homey automatically serves all videos as WebRTC to the frontend as of Homey Pro (Early 2023), Homey Pro mini and Homey Self-Hosted Server version 12.12.0. This makes it possible to show the videos on the Homey Web App, as well as make the videos available outside of your local network. Developers can opt out of this by passing the disableWebRTCProxy: true option while creating the video (see Apps SDK - ManagerVideos)

Getting Started with Videos

To register a camera stream, your app needs to ask ManagerVideos first to create a video. Then, attach the video to your Device by calling Device.setCameraVideo. Note that when a device has both an image and video with the same id then the image will be used as a background image for the video while it is loading.

Example — WebRTC

This example shows a basic WebRTC camera stream.

/drivers/my-webrtc-camera/device.mjs

import Homey from 'homey';

export default class MyWebRTCDevice extends Homey.Device {

    /*
     * WebRTC works by creating an offer SDP in the frontend, exchanging it for 
     * an answer SDP through the cameras API, and using that answer SDP in the
     * frontend to set up the connection.
     */
    async onInit() {
        try {
            const video = await this.homey.videos.createVideoWebRTC();

            /*
             * This listener is called when the user opens the camera stream in the
             * mobile app. The argument is an SDP offer generated by the mobile appp.
             */
            video.registerOfferListener(async (offerSdp) => {
                // Normally, you would call an API to exchange an SDP offer for an SDP answer
                const result = await this.oAuth2Client.createStream(offerSdp);
                return {
                    answerSdp: result.answerSdp,
                };
            });

            /*
             * Attach the camera to the device.
             */
            await this.setCameraVideo('main', 'Main Camera', video);
        } catch (err) {
            this.error('Error creating camera:', err);
        }   
    }
    
}

Example — WebRTC without Data Channel

This example shows a WebRTC camera without a data channel, and a keepalive listener.

/drivers/my-webrtc-camera/device.mjs

import Homey from 'homey';

export default class MyWebRTCDevice extends Homey.Device {

    /*
     * Some cameras require a data channel in order to work, while other cameras
     * only work when the offer does not contain a data channel. This can be
     * customized through the options object in the createCamera method.
     *
     * There are also cameras that only keep their stream open for a few minutes.
     * These can often be extended through an API call. The keep alive listener
     * can be used to send such a request.
     */
    async onInit() {
        try {
            const video = await this.homey.videos.createVideoWebRTC({
                dataChannel: false, // default: true
            });

            /*
             * The offer listener now also returns a stream ID next to the anwer
             * SDP. This stream ID can be used to identify the stream in the
             * keep alive listener.
             */
            video.registerOfferListener(async (offerSdp) => {
                // Normally, you would call an API to exchange an SDP offer for an SDP answer
                const result = await this.oAuth2Client.createStream(offerSdp);
                return {
                    answerSdp: result.answerSdp,
                    streamId: result.streamId,
                };
            });

            /*
             * The keep alive callback has a streamId argument that can be used
             * to identify the stream. Most APIs require such an identifier in
             * the request to extend the stream.
             */
            video.registerKeepAliveListener(async (streamId) => {
                // Normally, you would call an API to keep the stream alive
                await this.oAuth2Client.extendStream(streamId);
            });

            await this.setCameraVideo('main', 'Main Camera', video);
        } catch (err) {
            this.error('Error creating camera:', err);
        }   
    }
    
}

Example — RTSP

This example shows an RTSP camera, which is as simple as providing an URL. In this example, we use HTTP Basic Authentication (username:password@...) in the URL.

/drivers/my-rtsp-camera/device.mjs

import Homey from 'homey';

export default class MyRTSPDevice extends Homey.Device {

    /*
     * To play an RTSP stream, you simply need to return the URL to the stream
     * from the video url listener. Some streams require authentication in
     * different formats. This example uses query parameters for authentication.
     */
    async onInit() {        
        try {
            const video = await this.homey.videos.createVideoRTSP({
                allowInvalidCertificates: true,
                demuxer: 'h265',
            });

            /*
             * The video url listener takes no arguments. It simply builds the
             * URL to the RTSP stream using the username and password.
             */
            video.registerVideoUrlListener(async () => {
                // Get the username and password that were set during pairing
                const {
                    username,
                    password,
                 } = this.getSettings();
         
                // Normally, you would get the device's IP from Discovery, or another method
                return {
                    url: `rtsp://${username}:${password}@192.168.1.100:554/stream`
                };
            });

            /*
             * Attach the camera to the device.
             */
            await this.setCameraVideo('main', 'Main Camera', video);
        } catch (err) {
            this.error('Error creating camera:', err);
        }    
    }
}

Example — RTMP

This example shows an RTMP camera, which is as simple as providing an URL. It's very similar to RTSP.

/drivers/my-rtmp-camera/device.mjs

import Homey from 'homey';

export default class MyRTMPDevice extends Homey.Device {

    async onInit() {        
        try {
            const video = await this.homey.videos.createVideoRTMP();

            /*
             * The video url listener takes no arguments. It simply builds the
             * URL to the RTMP stream.
             */
            video.registerVideoUrlListener(async () => {         
                // Normally, you would get the device's IP from Discovery, or another method
                return {
                    url: `rtmp://@192.168.1.100:1935`
                };
            });

            /*
             * Attach the camera to the device.
             */
            await this.setCameraVideo('main', 'Main Camera', video);
        } catch (err) {
            this.error('Error creating camera:', err);
        }    
    }
}

Example — HLS

This example shows an HLS camera, which is as simple as providing an URL. It's very similar to RTSP.

/drivers/my-hls-camera/device.mjs

import Homey from 'homey';

export default class MyHLSDevice extends Homey.Device {

    async onInit() {        
        try {
            const video = await this.homey.videos.createVideoHLS();

            /*
             * The video url listener takes no arguments. It simply builds the
             * URL to the HLS stream.
             */
            video.registerVideoUrlListener(async () => {         
                // Normally, you would get the device's IP from Discovery, or another method
                return {
                    url: `http://@192.168.1.100/stream.m3u8`
                };
            });

            /*
             * Attach the camera to the device.
             */
            await this.setCameraVideo('main', 'Main Camera', video);
        } catch (err) {
            this.error('Error creating camera:', err);
        }    
    }
}

Example — DASH

This example shows an DASH camera, which is as simple as providing an URL. It's very similar to RTSP.

/drivers/my-dash-camera/device.mjs

import Homey from 'homey';

export default class MyDASHDevice extends Homey.Device {

    async onInit() {        
        try {
            const video = await this.homey.videos.createVideoDASH();

            /*
             * The video url listener takes no arguments. It simply builds the
             * URL to the DASH stream.
             */
            video.registerVideoUrlListener(async () => {         
                // Normally, you would get the device's IP from Discovery, or another method
                return {
                    url: `http://@192.168.1.100/stream.mpd`
                };
            });

            /*
             * Attach the camera to the device.
             */
            await this.setCameraVideo('main', 'Main Camera', video);
        } catch (err) {
            this.error('Error creating camera:', err);
        }    
    }
}

Apps SDK Reference

Please refer to ManagerVideos in the Apps SDK Reference to learn more about videos in your app.