Skip to content

Commit

Permalink
chore(docs): Improve usage & example documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
Steven Vancoillie committed May 5, 2020
1 parent 20b783b commit ff020a6
Show file tree
Hide file tree
Showing 4 changed files with 134 additions and 64 deletions.
46 changes: 40 additions & 6 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,19 +14,53 @@ If your changes cause problems with how the library was used before,
don't forget to write `BREAKING CHANGE:` inside the commit message body,
followed by a description of what has changed and how to adapt for it.

We use `node` and `yarn` for any development related things, so make sure you
have those installed. If you want to run the examples against a test RTSP server,
you'll need to have a working `docker` environment with access to docker hub.

### Testing

Make sure your changes pass linting and unit testing locally to save time with your PR,
by running `yarn test`.
If you add a new feature, please write a new unit test to catch any future regressions.

Most components have unit tests, and basic proper behaviour is always
tested, but we don't have full coverage (yet) of all the component code.
If you contribute a new component, please make sure it has appropriate
unit tests with sufficient coverage.

You can run all test with:
### Code formatting

```
npm run test
```
We use [prettier](https://prettier.io/) to automatically format code, and this is verified
during testing (part of linting).
To make sure tests don't fail on format problems, it's recommended to use a prettier plugin
for you editor, or to run `yarn prettier:fix` before committing any changes.

## Getting started

or
After cloning this repository, run `yarn` to install all dependencies.
The easiest way to get started is to get the examples up and running,
so you can test any changes you make.

There are two sets of examples: those that expect a camera backend,
and those that work with a test video provided by an RTSP server that
you can run locally via this library.

Run `yarn dev` to build the library, run a local RTSP test server, and serve
the examples. You'll see a link to a port on `localhost` (usually 8080).

## Continuous integration

Automated tests are run on the master branch and pull requests with GitHub Actions,
for which the configuration can be found in the `.github/workflows/ci.yml` file.
When tags are pushed, an automated deploy will release to both Github and NPM.
Any tags that are prereleases will be tagged `next` for NPM, otherwise `latest` is used.

To release, make sure you are on the master branch and run:

```
yarn test
yarn release
git push --follow-tags
```

after which the pushed tag will cause a build + deploy through GitHub Actions.
75 changes: 20 additions & 55 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@

[ci-image]: https://github.com/AxisCommunications/media-stream-library-js/workflows/CI/badge.svg
[ci-url]: https://github.com/AxisCommunications/media-stream-library-js/actions

[npm-image]: https://img.shields.io/npm/v/media-stream-library.svg
[npm-url]: https://www.npmjs.com/package/media-stream-library

Expand All @@ -25,20 +24,6 @@ alias: {

You can look at the `webpack.config.js` to see how it's used for building the bundle.

## Structure

The library contains a collection of components that can be connected
together to form media pipelines.
The components are a low-level abstraction on top of Node streams to allow two-way
communication, while media pipelines are sets of connected components with methods
that allow you to control the pipeline, and easily add/remove components.

Components can be categorized as:

- sources (socket, file, ...)
- transforms (parsers, depay, muxers, ...)
- sinks (HTML5 element, file, ...)

## Installation

Make sure you have Node installed on your machine.
Expand Down Expand Up @@ -68,67 +53,47 @@ Although RTP streams is the main focus, the library is not limited
to handling RTP streams. Contributions of new components/pipelines are
always welcome.

### Importing

You can directly include the `media-stream-library.min.js` file in your browser
(check the browser example):

```
<script src="media-stream-library.min.js"></script>
```

or import it into your javascript code:
or import it into your javascript code if you bundle it yourself:

```
import {components, pipelines} from 'media-stream-library';
```

Check the `examples` section to see how these can be used in practice.
To use the browser example, run:
### Components and pipelines

```
npm run examples
```
The library contains a collection of components that can be connected
together to form media pipelines.
The components are a low-level abstraction on top of Node streams to allow two-way
communication, while media pipelines are sets of connected components with methods
that allow you to control the pipeline, and easily add/remove components.

or
Components can be categorized as:

```
yarn examples
```
- sources (socket, file, ...)
- transforms (parsers, depay, muxers, ...)
- sinks (HTML5 element, file, ...)

## Debugging
To build a pipeline, you can connect the required components.
A number common pipelines are exported directly for convenience.

Check the `examples` section to see how these can be used in your own code.
To run the examples yourself, you'll need to clone this repository loccally
and follow the developer instructions.

The easiest way to debug is to use a Node CLI pipeline (see examples) and
log what is happening to your component(s).
## Debugging

In the browser, you can set `localStorage.debug = 'msl:*'` to log everything
related to just this library (make sure to reload the page after setting the value).

## Contributing

Please read our [contributing guidelines](CONTRIBUTING.md) before making pull requests.

### Code formatting

We use [prettier](https://prettier.io/) to automatically format code, and this is verified
during testing (part of linting).
To make sure tests don't fail on format problems, it's recommended to use a prettier plugin
for you editor, or to run `yarn prettier:fix` before committing any changes.

### Testing

Make sure your changes pass linting and unit testing locally to save time with your PR,
by running `yarn test`.
If you add a new feature, please write a new unit test to catch any future regressions.

## Continuous integration

Automated tests are run on the master branch and pull requests with GitHub Actions,
for which the configuration can be found in the `.github/workflows/ci.yml` file.
When tags are pushed, an automated deploy will release to both Github and NPM.
Any tags that are prereleases will be tagged `next` for NPM, otherwise `latest` is used.

To release, make sure you are on the master branch and run:
```
yarn release
git push --follow-tags
```
after which the pushed tag will cause a build + deploy through GitHub Actions.
5 changes: 3 additions & 2 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@
"prettier:check": "prettier --check 'lib/**/*.{ts,js}'",
"prettier:fix": "prettier --write 'lib/**/*.{ts,js}' --fix --loglevel silent",
"rtsp": "rtsp-ws-server/start.sh",
"dev": "webpack --mode development --watch",
"examples": "webpack --mode development && http-server examples/browser",
"examples": "http-server examples/browser",
"dev": "yarn build && concurrently \"yarn webpack --mode development --watch\" \"yarn rtsp\" \"yarn examples\"",
"version": "conventional-changelog -p angular -i CHANGELOG.md -s && git add CHANGELOG.md",
"release": "yarn version --new-version `node node_modules/.bin/conventional-recommended-bump -p angular`"
},
Expand Down Expand Up @@ -56,6 +56,7 @@
"@typescript-eslint/eslint-plugin": "2.30.0",
"@typescript-eslint/parser": "2.30.0",
"babel-loader": "8.1.0",
"concurrently": "5.2.0",
"conventional-changelog-cli": "2.0.31",
"conventional-recommended-bump": "6.0.5",
"core-js": "3.6.5",
Expand Down
72 changes: 71 additions & 1 deletion yarn.lock
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2852,6 +2852,21 @@ concat-stream@^2.0.0:
readable-stream "^3.0.2"
typedarray "^0.0.6"

[email protected]:
version "5.2.0"
resolved "https://registry.yarnpkg.com/concurrently/-/concurrently-5.2.0.tgz#ead55121d08a0fc817085584c123cedec2e08975"
integrity sha512-XxcDbQ4/43d6CxR7+iV8IZXhur4KbmEJk1CetVMUqCy34z9l0DkszbY+/9wvmSnToTej0SYomc2WSRH+L0zVJw==
dependencies:
chalk "^2.4.2"
date-fns "^2.0.1"
lodash "^4.17.15"
read-pkg "^4.0.1"
rxjs "^6.5.2"
spawn-command "^0.0.2-1"
supports-color "^6.1.0"
tree-kill "^1.2.2"
yargs "^13.3.0"

console-browserify@^1.1.0:
version "1.1.0"
resolved "https://registry.yarnpkg.com/console-browserify/-/console-browserify-1.1.0.tgz#f0241c45730a9fc6323b206dbf38edc741d0bb10"
Expand Down Expand Up @@ -3276,6 +3291,11 @@ date-fns@^1.27.2:
resolved "https://registry.yarnpkg.com/date-fns/-/date-fns-1.30.1.tgz#2e71bf0b119153dbb4cc4e88d9ea5acfb50dc05c"
integrity sha512-hBSVCvSmWC+QypYObzwGOd9wqdDpOt+0wl0KbU+R+uuZBS1jN8VsD1ss3irQDknRj5NvxiTF6oj/nDRnN/UQNw==

date-fns@^2.0.1:
version "2.12.0"
resolved "https://registry.yarnpkg.com/date-fns/-/date-fns-2.12.0.tgz#01754c8a2f3368fc1119cf4625c3dad8c1845ee6"
integrity sha512-qJgn99xxKnFgB1qL4jpxU7Q2t0LOn1p8KMIveef3UZD7kqjT3tpFNNdXJelEHhE+rUgffriXriw/sOSU+cS1Hw==

date-now@^0.1.4:
version "0.1.4"
resolved "https://registry.yarnpkg.com/date-now/-/date-now-0.1.4.tgz#eaf439fd4d4848ad74e5cc7dbef200672b9e345b"
Expand Down Expand Up @@ -7254,6 +7274,15 @@ read-pkg@^3.0.0:
normalize-package-data "^2.3.2"
path-type "^3.0.0"

read-pkg@^4.0.1:
version "4.0.1"
resolved "https://registry.yarnpkg.com/read-pkg/-/read-pkg-4.0.1.tgz#963625378f3e1c4d48c85872b5a6ec7d5d093237"
integrity sha1-ljYlN48+HE1IyFhytabsfV0JMjc=
dependencies:
normalize-package-data "^2.3.2"
parse-json "^4.0.0"
pify "^3.0.0"

read-pkg@^5.2.0:
version "5.2.0"
resolved "https://registry.yarnpkg.com/read-pkg/-/read-pkg-5.2.0.tgz#7bf295438ca5a33e56cd30e053b34ee7250c93cc"
Expand Down Expand Up @@ -7659,6 +7688,13 @@ rxjs@^6.4.0:
dependencies:
tslib "^1.9.0"

rxjs@^6.5.2:
version "6.5.5"
resolved "https://registry.yarnpkg.com/rxjs/-/rxjs-6.5.5.tgz#c5c884e3094c8cfee31bf27eb87e54ccfc87f9ec"
integrity sha512-WfQI+1gohdf0Dai/Bbmk5L5ItH5tYqm3ki2c5GdWhKjalzjg93N3avFjVStyZZz+A2Em+ZxKH5bNghw9UeylGQ==
dependencies:
tslib "^1.9.0"

safe-buffer@^5.0.1, safe-buffer@^5.1.0, safe-buffer@^5.1.1, safe-buffer@^5.1.2, safe-buffer@~5.1.0, safe-buffer@~5.1.1:
version "5.1.2"
resolved "https://registry.yarnpkg.com/safe-buffer/-/safe-buffer-5.1.2.tgz#991ec69d296e0313747d59bdfd2b745c35f8828d"
Expand Down Expand Up @@ -7938,6 +7974,11 @@ source-map@^0.7.3:
resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.7.3.tgz#5302f8169031735226544092e64981f751750383"
integrity sha512-CkCj6giN3S+n9qrYiBTX5gystlENnRW5jZeNLHpe6aue+SrHcG5VYwujhW9s4dY31mEGsxBDrHR6oI69fTXsaQ==

spawn-command@^0.0.2-1:
version "0.0.2-1"
resolved "https://registry.yarnpkg.com/spawn-command/-/spawn-command-0.0.2-1.tgz#62f5e9466981c1b796dc5929937e11c9c6921bd0"
integrity sha1-YvXpRmmBwbeW3Fkpk34RycaSG9A=

spdx-correct@^3.0.0:
version "3.1.0"
resolved "https://registry.yarnpkg.com/spdx-correct/-/spdx-correct-3.1.0.tgz#fb83e504445268f154b074e218c87c003cd31df4"
Expand Down Expand Up @@ -8228,7 +8269,7 @@ strip-json-comments@~2.0.1:
resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-2.0.1.tgz#3c531942e908c2697c0ec344858c286c7ca0a60a"
integrity sha1-PFMZQukIwml8DsNEhYwobHygpgo=

[email protected]:
[email protected], supports-color@^6.1.0:
version "6.1.0"
resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-6.1.0.tgz#0764abc69c63d5ac842dd4867e8d025e880df8f3"
integrity sha512-qe1jfm1Mg7Nq/NSh6XE24gPXROEVsWHxC1LIx//XNlD9iw7YZQGjZNjYN7xGaEG6iKdA8EtNFW6R0gjnVXp+wQ==
Expand Down Expand Up @@ -8499,6 +8540,11 @@ tr46@^1.0.1:
dependencies:
punycode "^2.1.0"

tree-kill@^1.2.2:
version "1.2.2"
resolved "https://registry.yarnpkg.com/tree-kill/-/tree-kill-1.2.2.tgz#4ca09a9092c88b73a7cdc5e8a01b507b0790a0cc"
integrity sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==

trim-newlines@^1.0.0:
version "1.0.0"
resolved "https://registry.yarnpkg.com/trim-newlines/-/trim-newlines-1.0.0.tgz#5887966bb582a4503a41eb524f7d35011815a613"
Expand Down Expand Up @@ -9063,6 +9109,14 @@ yargs-parser@^13.1.0:
camelcase "^5.0.0"
decamelize "^1.2.0"

yargs-parser@^13.1.2:
version "13.1.2"
resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-13.1.2.tgz#130f09702ebaeef2650d54ce6e3e5706f7a4fb38"
integrity sha512-3lbsNRf/j+A4QuSZfDRA7HRSfWrzO0YjqTJd5kjAq37Zep1CEgaYmrH9Q3GwPiB9cHyd1Y1UwggGhJGoxipbzg==
dependencies:
camelcase "^5.0.0"
decamelize "^1.2.0"

yargs-parser@^18.1.1:
version "18.1.1"
resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-18.1.1.tgz#bf7407b915427fc760fcbbccc6c82b4f0ffcbd37"
Expand Down Expand Up @@ -9105,6 +9159,22 @@ [email protected], yargs@^15.3.1:
y18n "^4.0.0"
yargs-parser "^18.1.1"

yargs@^13.3.0:
version "13.3.2"
resolved "https://registry.yarnpkg.com/yargs/-/yargs-13.3.2.tgz#ad7ffefec1aa59565ac915f82dccb38a9c31a2dd"
integrity sha512-AX3Zw5iPruN5ie6xGRIDgqkT+ZhnRlZMLMHAs8tg7nRruy2Nb+i5o9bwghAogtM08q1dpr2LVoS8KSTMYpWXUw==
dependencies:
cliui "^5.0.0"
find-up "^3.0.0"
get-caller-file "^2.0.1"
require-directory "^2.1.1"
require-main-filename "^2.0.0"
set-blocking "^2.0.0"
string-width "^3.0.0"
which-module "^2.0.0"
y18n "^4.0.0"
yargs-parser "^13.1.2"

[email protected], yauzl@^2.10.0:
version "2.10.0"
resolved "https://registry.yarnpkg.com/yauzl/-/yauzl-2.10.0.tgz#c7eb17c93e112cb1086fa6d8e51fb0667b79a5f9"
Expand Down

0 comments on commit ff020a6

Please sign in to comment.