A friendly interface for built-in video sources, such as cameras.

Camera lets you open a camera, change its settings, take snapshots, and show a live preview in an HTML element.

The current API covers the common case of opening and using a single camera. It does not yet expose the full range of browser media features.

Commands and information pass between Elm and the browser through ports. Large data items are not passed to Elm, but are addressed through opaque handles instead.

Camera workflow

Using a camera follows a small request-and-result loop:

1. Call open, or use openWithOptions to choose a device and send initial Configuration.Constraints. The regular open function starts with Configuration.defaultConstraints, where every field is Nothing.
2. Handle OpenCompleted. A successful result contains an OpenedCamera with its ID, capabilities, and active settings.
3. Keep your constraints in your application model. To change the camera, update that value and send the complete new constraints with configure.
4. Handle ConfigureCompleted. A successful result contains the active settings the browser actually applied.

Constraints express what your application wants, while settings describe what the browser is using. The browser may choose compatible values that differ from the request, so use the returned settings as the current camera state. Both completion events return Err CameraError when their operation fails.

Installation

Install the Elm package:

elm install mbr/elm-camera

Elm packages cannot declare ports. Make Main.elm a port module, or add an application-owned port module containing these declarations:

import Camera exposing (CommandPort, EventPort)


port cameraCmd : CommandPort msg


port cameraMsg : EventPort msg

The JavaScript runtime expects the exact port names cameraCmd and cameraMsg.

Copy js/elm-camera.js into the browser assets. Load the runtime and compiled Elm application, initialize Elm, and then initialize the camera runtime:

<script src="elm-camera.js"></script>
<script src="app.js"></script>
<script>
var app = Elm.Main.init({
  node: document.getElementById("elm")
});
var cameraRuntime = ElmCamera.initApp(app);
</script>

initApp returns a small runtime object. Most applications can leave it running for the lifetime of the page. If your Elm application is removed or replaced, call shutdown() to release its cameras, snapshots, and any URLs created for those snapshots.

If the cameraCmd port is not present, initApp simply returns null. Application-owned browser integrations can resolve a retained snapshot handle with cameraRuntime.snapshotBlob(handle), or read an open camera's current frame with await cameraRuntime.currentFrame(cameraId). A current frame is a full-size ImageBitmap owned by the caller and must be closed after use. Use the corresponding encoders and decoders at application port boundaries.

Camera access requires a secure browser context, so use HTTPS in production. Browsers normally treat http://localhost, http://127.0.0.1, and http://[::1] as trustworthy for local development. A phone visiting a plain HTTP address on the local network is not using localhost and generally needs HTTPS.

Basic usage

Call openRear from a user action, subscribe to camera events, and track the pending operation in your application's model until OpenCompleted arrives:

import Camera
import CameraPorts as Ports


type Model
    = Opening
    | Ready Camera.OpenedCamera
    | Failed Camera.CameraError


type Msg
    = CameraEvent Camera.Event


init : () -> ( Model, Cmd Msg )
init _ =
    ( Opening, Camera.openRear Ports.cameraCmd )


update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        CameraEvent (Camera.OpenCompleted result) ->
            case result of
                Ok camera ->
                    ( Ready camera, Cmd.none )


                Err error ->
                    ( Failed error, Cmd.none )


        CameraEvent _ ->
            ( model, Cmd.none )


subscriptions : Model -> Sub Msg
subscriptions _ =
    Sub.map CameraEvent (Camera.subscribe Ports.cameraMsg)

A successful open returns the camera ID together with its capabilities and active settings. Camera acquisition and permission failures arrive as Err CameraError.

Ports

CommandPort and EventPort match the two application-owned ports shown above. Pass those ports to camera commands and subscriptions.

Commands and events

Only one camera can be opening at a time. Wait for a command's completion event before sending another command that changes the same camera.

The named functions below cover the usual commands. send is available when it is more convenient to work with Command values directly. subscribe receives both replies to commands and events generated by an open camera.

Opening and devices

open uses the browser's default camera, which is usually the right choice for desktop computers and USB webcams. openFront and openRear ask for a camera facing in a particular direction, but still allow the browser to choose another camera when needed.

Use openWithOptions to choose a device or ask for particular initial settings. devices can help with device pickers, but opening a camera is the only way to know whether it is available. If the browser lists a camera without an ID, devices returns Err DeviceInformationUnavailable. Opening a camera and then calling devices again will usually reveal IDs and labels.

Camera settings and facing modes are defined in Camera.Configuration.

Camera information and configuration

Camera configuration has four parts:

• supportedConstraints tells you which setting names the browser knows.
• capabilities tells you what an open camera can do.
• Configuration.Constraints contains the values your application asks for.
• settings tells you what the browser is actually using.

Keep your constraints in your application model when making several changes. A property the browser does not report is Nothing. Even when a property is supported, a particular value or combination may still fail. After calling configure, use the Configuration.Settings from ConfigureCompleted as the camera's current settings.

For example, request continuous autofocus only when the camera advertises it:

import Camera.Configuration as Configuration


enableContinuousFocus :
    CommandPort msg
    -> OpenedCamera
    -> Configuration.Constraints
    -> Cmd msg
enableContinuousFocus commandPort camera constraints =
    if
        camera.capabilities.focusMode
            |> Maybe.withDefault []
            |> List.member Configuration.Continuous
    then
        configure commandPort
            camera.id
            { constraints
                | focusMode = Just Configuration.Continuous
            }


    else
        Cmd.none

See Camera.Configuration for the control types and a detailed explanation of capabilities, constraints, and settings.

Preview

preview creates an HTML element showing the camera's live video. It fills its element by default and may crop video edges. Use Camera.Preview to show the complete frame instead, and add any other HTML attributes the application needs:

import Camera.Preview as Preview




Camera.preview camera.id
    [ Preview.fit Preview.Contain
    , Html.Attributes.class "my-viewfinder"
    ]

Removing the element does not close the camera, and adding it again reconnects the preview. The same camera can appear in more than one preview, and regular HTML or SVG can be placed over it.

Browser integrations

Application-owned browser integrations can address an open camera without exposing its ID representation. encodeId sends the ID through a port, and idDecoder reads it when the integration responds.

Snapshots

capturePng takes a snapshot of the current frame. The PNG stays in the browser rather than passing through Elm, and SnapshotCaptured returns its metadata and an opaque handle.

A successful snapshot is kept until you call discardSnapshot for its handle, or until the camera runtime shuts down. Removing the handle from your Elm model, removing an image from the page, or closing the camera does not release it. Use snapshotObjectUrl to show or download the PNG, then call discardSnapshot when it is no longer needed.

import Camera.Snapshot as Snapshot


capture : CommandPort msg -> OpenedCamera -> Cmd msg
capture commandPort camera =
    capturePng commandPort camera.id Snapshot.defaultOptions

See Camera.Snapshot for snapshot options, metadata, and URL cleanup.

Lifecycle

setEnabled pauses or resumes camera output without releasing the camera. close releases the camera and makes its ID stale. Removing every preview does not close the camera.

A camera can also be muted, unmuted, or ended by the browser or device. These changes arrive through CameraMuted, CameraUnmuted, and CameraEnded. Camera and snapshot IDs are never reused, so an old ID cannot accidentally refer to a new resource.

Errors

Command failures arrive in completion events as Err values. If a message from the runtime cannot be read, subscribe produces RuntimeError containing a ProtocolFailure instead of crashing the Elm application.