# rtc-captureconfig

> Simple string definition -> WebRTC constraints

Latest version **4.4.1** (published 2023-05-26) · Apache 2.0 license · 0 weekly downloads

## Install

```sh
npm install rtc-captureconfig
pnpm add rtc-captureconfig
yarn add rtc-captureconfig
bun add rtc-captureconfig
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.4.1 |
| Published | 2023-05-26 |
| First published | 2013-10-17 |
| Weekly downloads | 0 |
| License | Apache 2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 63.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 13 |
| Author | Damon Oehlman |
| Maintainers | nathanoehlman, damonoehlman |
| Keywords | webrtc, rtc.io |

## Links

- npm: https://www.npmjs.com/package/rtc-captureconfig
- Repository: https://github.com/rtc-io/rtc-captureconfig
- Homepage: https://github.com/rtc-io/rtc-captureconfig#readme
- Issues: https://github.com/rtc-io/rtc-captureconfig/issues
- npm.io page: https://npm.io/package/rtc-captureconfig

## Dependencies (4)

- [cog](https://npm.io/package/cog.md) ^1.1.0
- [rtc-core](https://npm.io/package/rtc-core.md) ^4.0.0
- [detect-browser](https://npm.io/package/detect-browser.md) ^4.6.0
- [compare-versions](https://npm.io/package/compare-versions.md) ^1.1.2

## Recent versions

- 4.4.1 (latest) — 2023-05-26
- 4.4.0 — 2019-08-19
- 4.3.0 — 2019-01-21
- 4.2.0 — 2018-10-10
- 4.1.0 — 2016-12-22
- 4.0.0 — 2016-09-19
- 3.0.0 — 2015-09-07
- 2.2.0 — 2015-06-22
- 2.1.1 — 2014-10-22
- 2.1.0 — 2014-08-07
- 2.0.0 — 2014-08-04
- 1.0.0 — 2014-06-27
- 0.4.0 — 2013-11-14
- 0.3.2 — 2013-11-07
- 0.3.1 — 2013-10-30
- … 2 more at https://npm.io/package/rtc-captureconfig/versions

## README

# rtc-captureconfig

This is a simple parser that takes a string of text and determines what
that means in the context of WebRTC.


[![NPM](https://nodei.co/npm/rtc-captureconfig.png)](https://nodei.co/npm/rtc-captureconfig/)

[![Build Status](https://img.shields.io/travis/rtc-io/rtc-captureconfig.svg?branch=master)](https://travis-ci.org/rtc-io/rtc-captureconfig) [![unstable](https://img.shields.io/badge/stability-unstable-yellowgreen.svg)](https://github.com/dominictarr/stability#unstable)
[![Gitter chat](https://badges.gitter.im/rtc-io/discuss.png)](https://gitter.im/rtc-io/discuss)



## Why?

It provides a simple, textual way of describing your requirements for
media capture.  Trying to remember the structure of the constraints object
is painful.

## How

A simple text string is converted to an intermediate JS object
representation, which can then be converted to a getUserMedia constraints
data structure using a `toConstraints()` call.

For example, the following text input:

```
camera min:1280x720 max:1280x720 min:15fps max:25fps
```

Is converted into an intermedia representation (via the `CaptureConfig`
utility class) that looks like the following:

```js
{
  camera: 0,
  microphone: 0,
  res: {
    min: { w: 1280, h: 720 },
    max: { w: 1280, h: 720 }
  },

  fps: {
    min: 15,
    max: 25
  }
}
```

Which in turn is able to be converted into the appropriate browser media constraints
for a `getUserMedia` call.

For Chrome/Firefox 37 and below

```js
{
  audio: true,
  video: {
    mandatory: {},
    optional: [
      { minFrameRate: 15 },
      { maxFrameRate: 25 }

      { minWidth: 1280 },
      { maxWidth: 1280 },
      { width: 1280 },

      { minHeight: 720 },
      { maxHeight: 720 },
      { height: 720 }
    ]
  }
}
```

For Firefox 38+

```js
{
  audio: true,
  video: {
    mandatory: {},
    optional: [
      { frameRate: { min: 15, max: 25 },
      { width: 1280 },
      { height: 720 }
    ]
  }
}
```


### Experimental: Targeted Device Capture

While the `rtc-captureconfig` module itself doesn't contain any media
identification logic, it is able to the sources information from a
`MediaStreamTrack.getSources` call to generate device targeted constraints.

For instance, the following example demonstrates how we can request
`camera:1` (the 2nd video device on our local machine) when we are making
a getUserMedia call:

```js
// load in capture config
var capture = require('rtc-captureconfig');

// pull in the getusermedia helper module
// see: https://github.com/HenrikJoreteg/getUserMedia
var getUserMedia = require('getusermedia');

// get the sources
MediaStreamTrack.getSources(function(sources) {
  var constraints = capture('camera:1').toConstraints({ sources: sources });

  /* here is an example of what the generated constraints actually look like
  var constraints = {
    audio:true,
    video: {
      mandatory: {},
      optional: [
        { sourceId: '30a3f6408175c22df739bcbf9573d841d9f99289' }
      ]
    }
  };
  */

  // get user media
  getUserMedia(constraints, function(err, stream) {
    if (err) {
      return console.log('Could not capture stream: ', err);
    }

    console.log('captured stream: ', stream);
  });
});
```

It's worth noting that if the requested device does not exist on the
machine (in the case above, if your machine only has a single webcam - as
is common) then no device selection constraints will be generated (i.e.
the standard `{ video: true, audio: true }` constraints will be returned
from the `toConstraints` call).

### Experimental: Screen Capture

If you are working with chrome and serving content of a HTTPS connection,
then you will be able to experiment with experimental getUserMedia screen
capture.

In the simplest case, screen capture can be invoked by using the capture
string of:

```
screen
```

Which generates the following contraints:

```js
{
  audio: false,
  video: {
    mandatory: {
      chromeMediaSource: 'screen'
    },

    optional: []
  }
}
```

## Reference

### CaptureConfig

This is a utility class that is used to update capture configuration
details and is able to generate suitable getUserMedia constraints based
on the configuration.

#### camera(index)

Update the camera configuration to the specified index

#### microphone(index)

Update the microphone configuration to the specified index

#### screen(target)

Specify that we would like to capture the screen

#### max(data)

Update a maximum constraint.  If an fps constraint this will be directed
to the `maxfps` modifier.

#### maxfps(data)

Update the maximum fps

#### min(data)

Update a minimum constraint.  This can be either related to resolution
or FPS.

#### minfps(data)

Update the minimum fps

#### toConstraints(opts?)

Convert the internal configuration object to a valid media constraints
representation.  In compatible browsers a list of media sources can
be passed through in the `opts.sources` to create contraints that will
target a specific device when captured.

It is also possible to override the autodetected constraint output type by
passing in the desired output type in `opts.constraintType`. (`legacy` for
Chrome style constraints, `standard` for Firefox 38+ constraints)

```js
var media = require('rtc-media');
var capture = require('rtc-captureconfig');

// get the sources
MediaStreamTrack.getSources(function(sources) {
  // get the cameras
  var cameras = sources.filter(function(info) {
    return info && info.kind === 'video';
  });

  // create videos
  var videos = cameras.map(function(info, idx) {
    return media(capture('camera:' + idx).toConstraints({ sources: sources }));
  });

  // render the videos
  videos.forEach(function(vid) {
    vid.render(document.body);
  });
});
```

### "Internal" methods

#### _parseRes(data)

Parse a resolution specifier (e.g. 1280x720) into a simple JS object
(e.g. { w: 1280, h: 720 })

## License(s)

### Apache 2.0

Copyright 2014 National ICT Australia Limited (NICTA)

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

---
_Source: https://npm.io/package/rtc-captureconfig · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._