Pion MediaDevices

Go implementation of the MediaDevices API

MediaDevices provides access to connected media input devices like cameras and microphones, as well as screen sharing. It can also be used to encode your video/audio stream to various codec selections.

The focus of the project has been to seek out a simple and elegant design for writing media pipelines.

Install

go get -u github.com/pion/mediadevices

Usage

The following snippet shows how to capture a camera stream and store a frame as a jpeg image:

package main

import (
	"image/jpeg"
	"os"

	"github.com/pion/mediadevices"
	"github.com/pion/mediadevices/pkg/prop"

	// This is required to register camera adapter
	_ "github.com/pion/mediadevices/pkg/driver/camera" 
	// Note: If you don't have a camera or your adapters are not supported,
	//       you can always swap your adapters with our dummy adapters below.
	// _ "github.com/pion/mediadevices/pkg/driver/videotest"
)

func main() {
	stream, _ := mediadevices.GetUserMedia(mediadevices.MediaStreamConstraints{
		Video: func(constraint *mediadevices.MediaTrackConstraints) {
			// Query for ideal resolutions
			constraint.Width = prop.Int(600)
			constraint.Height = prop.Int(400)
		},
	})

	// Since track can represent audio as well, we need to cast it to 
	// *mediadevices.VideoTrack to get video specific functionalities
	track := stream.GetVideoTracks()[0]
	videoTrack := track.(*mediadevices.VideoTrack)
	defer videoTrack.Close()

	// Create a new video reader to get the decoded frames. Release is used 
	// to return the buffer to hold frame back to the source so that the buffer 
	// can be reused for the next frames.
	videoReader := videoTrack.NewReader(false)
	frame, release, _ := videoReader.Read()
	defer release()

	// Since frame is the standard image.Image, it's compatible with Go standard 
	// library. For example, capturing the first frame and store it as a jpeg image.
	output, _ := os.Create("frame.jpg")
	jpeg.Encode(output, frame, nil)
}

More Examples

• Webrtc - Use Webrtc to create a realtime peer-to-peer video call
• Face Detection - Use a machine learning algorithm to detect faces in a camera stream
• RTP Stream - Capture camera stream, encode it in H264/VP8/VP9, and send it to a RTP server
• HTTP Broadcast - Broadcast camera stream through HTTP with MJPEG

Available Media Inputs

Input	Linux	Mac	Windows
Camera	✔️	✔️	✔️
Microphone	✔️	✔️	✔️
Screen	✔️	✖️	✖️

Available Codecs

Video Codecs

x264

A free software library and application for encoding video streams into the H.264/MPEG-4 AVC compression format.

• Package: github.com/pion/mediadevices/pkg/codec/x264
• Installation:
  • Mac: brew install x264
  • Ubuntu: apt install libx264-dev

mmal

A framework to enable H264 hardware encoding for Raspberry Pi or boards that use VideoCore GPUs.

• Package: github.com/pion/mediadevices/pkg/codec/mmal
• Installation:
  • Raspbian: export PKG_CONFIG_PATH=/opt/vc/lib/pkgconfig

openh264

A codec library which supports H.264 encoding and decoding. It is suitable for use in real time applications.

• Package: github.com/pion/mediadevices/pkg/codec/openh264
• Installation: no installation needed, included as a static binary

vpx

A free software video codec library from Google and the Alliance for Open Media that implements VP8/VP9 video coding formats.

• Package: github.com/pion/mediadevices/pkg/codec/vpx
• Installation:
  • Mac: brew install libvpx
  • Ubuntu: apt install libvpx-dev

vaapi

An open source API that allows applications such as VLC media player or GStreamer to use hardware video acceleration capabilities (currently support VP8/VP9).

• Package: github.com/pion/mediadevices/pkg/codec/vaapi
• Installation:
  • Ubuntu: apt install libva-dev

Audio Codecs

opus

A totally open, royalty-free, highly versatile audio codec.

• Package: github.com/pion/mediadevices/pkg/codec/opus
• Installation:
  • Mac: brew install opus
  • Ubuntu: apt install libopus-dev

Benchmark

Result as of Nov 4, 2020 with Go 1.14 on a Raspberry pi 3, mediadevices can produce a 720p at 30 fps with <500ms latency video.

The test was taken by capturing a camera stream, decode raw frames, encode the video stream with mmal to H264, and send the stream through Webrtc.

FAQ

Failed to find the best driver that fits the constraints

mediadevices provides an automated driver discovery through GetUserMedia and GetDisplayMedia. In an oversimplified explanation, the discovery algorithm as followed:

1. Open all registered drivers
2. Get all properties (property describes what a driver is capable of, e.g. resolution, frame rate, etc.) from opened drivers
3. Find the best property that meets the criteria

So, when mediadevices returns failed to find the best driver that fits the constraints error, one of the following conditions might have occured:

• In your program, the driver has never been imported as a side effect, e.g. import _ github.com/pion/mediadevices/pkg/driver/camera
• Your constraint is too strict that there's no driver can fullfil your requirements. In this case, you can try to turn up the debug level by specifying the following environment variable: export PION_LOG_DEBUG=all
• Your driver is not supported/implemented. In this case, you can either wait for the maintainers to implement it. Or, you can implement it yourself and register it through RegisterDriverAdapter

Failed to find vpx/x264/mmal/opus codecs

Since mediadevices uses cgo to access video/audio codecs, it needs to find these libraries from the system. To do that, mediadevices uses pkg-config for library discovery.

If you see the following error message at compile time:

# pkg-config --cflags  -- vpx
Package vpx was not found in the pkg-config search path.
Perhaps you should add the directory containing `vpx.pc'
to the PKG_CONFIG_PATH environment variable
No package 'vpx' found
pkg-config: exit status 1

There are 2 common problems:

• The required codec library is not installed (vpx in this example). In this case, please refer to the available codecs.
• Pkg-config fails to find the .pc files for this codec (reference). In this case, you need to find where the codec library's .pc is stored, and let pkg-config knows with: export PKG_CONFIG_PATH=/path/to/directory.

Community

Pion has an active community on the Slack.

Follow the Pion Twitter for project updates and important WebRTC news.

We are always looking to support your projects. Please reach out if you have something to build! If you need commercial support or don't want to use public methods you can contact us at team@pion.ly

Contributing

Check out the contributing wiki to join the group of amazing people making this project possible:

• Lukas Herman - Original Author
• Atsushi Watanabe - VP8, Screencast, etc.

License

MIT License - see LICENSE for full text