# @sovpro/heos-stream

> Node.js streams for HEOS protocol communication over a socket

Latest version **1.0.3** (published 2020-06-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install @sovpro/heos-stream
pnpm add @sovpro/heos-stream
yarn add @sovpro/heos-stream
bun add @sovpro/heos-stream
```

## 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 | 1.0.3 |
| Published | 2020-06-17 |
| First published | 2019-12-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 13.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | sovpro |
| Maintainers | sovpro |
| Keywords | heos, protocol, stream |

## Links

- npm: https://www.npmjs.com/package/@sovpro/heos-stream
- Repository: https://github.com/sovpro/heos-stream
- Homepage: https://github.com/sovpro/heos-stream#readme
- Issues: https://github.com/sovpro/heos-stream/issues
- npm.io page: https://npm.io/package/@sovpro/heos-stream

## Dependencies (1)

- [@sovpro/delimited-stream](https://npm.io/package/@sovpro/delimited-stream.md) ^1.1.0

## Alternatives

- [byte-size](https://npm.io/package/byte-size.md) — 2.1M weekly downloads
- [speed-limiter](https://npm.io/package/speed-limiter.md) — 16.0K weekly downloads
- [@powersync/node](https://npm.io/package/@powersync/node.md) — 10.9K weekly downloads
- [@ledgerhq/coin-cardano](https://npm.io/package/@ledgerhq/coin-cardano.md) — 1.0K weekly downloads
- [@jayesol/jayeson.lib.streamfinder](https://npm.io/package/@jayesol/jayeson.lib.streamfinder.md) — 1.0K weekly downloads

## Recent versions

- 1.0.3 (latest) — 2020-06-17
- 1.0.2 — 2019-12-17
- 1.0.1 — 2019-12-17

## README

# Heos Stream

Node.js streams for HEOS protocol communication over a socket

## HeosStream

### Constructor

Construct an instance with a Socket obtainable via `net.createConnection()` or `new net.Socket()`

```js
const {HeosStream} = require ('@sovpro/heos-stream')
const heos_stream = new HeosStream (socket)
```
### Writing

Writing requires objects implementing a commmand object interface.

#### Command object interface

The comand interface is an object with a  string `command` and object `params` property. `command` represents the `host` and `pathname` of a HEOS command url*.


```js
const command_object = {
  command: 'string' ,
  params: {
    key: value ,
    // , key2: value 
    // , ...
  } 
}
heos_stream.write (command_object)
```

The key value pairs correspond to query string parameters that are appended to the HEOS command.

\* `host` and `pathname` are the command group and command according to the specification.

### Reading

Reading provides data objects that are one of:

 * HeosData
 * HeosResult
 * HeosEvent

#### HeosData

All data provided by HeosStream is a HeosData instance consisting of a message and command property. A HeosResult or HeosEvent is provided if the data is determined to a be a result or an event.

Properties:
 * `message` : A key value object
 * `command` : The command that caused this data 

#### HeosResult

HeosResult represents data that is known to be a command result.

Properties accompanying those from HeosData
 * `result` : A string that is either 'success' or 'fail'
 * `payload` : May be undefined, object or an array
 * `options` : May be undefined or an array

#### HeosEvent

HeosEvent represents data that is known to be a HEOS event.

Properties accompanying those from HeosData
  * `event` : A string name of the event (excluding 'event/' prefix)

## Filtered Streams

There are two streams emitting data filtered to results (HeosResult) or events (HeosEvent).

### HeosResultStream

An opt-in filtered stream that emits result (HeosResult) data with a command matching on of those provided to the constructor.

```js
const result_stream = new HeosResultStream ([
  'player/set_volume'  ,
  'player/set_mute'    ,
  'player/toggle_mute' , 
  // ...
])
heos_stream.pipe (result_stream)
result_stream.on ('data', result_data => {
  // result_data.command will be one of
  // the commands provided to the constructor
  const {command, message} = result_data
})
```

### HeosEventStream

An opt-in filtered stream that emits event (HeosEvent) data with a name matching one of those provided to the constructor.

```js
const event_stream = new HeosEventStream ([
  'player_volume_changed'  ,
  // ...
])
heos_stream.pipe (event_stream)
event_stream.on ('data', event_data => {
  // event_data.event will be one of
  // the events provided the constructor
  const {event} = event_data
})
```

## Links

* [HEOS by Denon](https://usa.denon.com/en/heos)
* [HEOS CLI Protocol Specification](https://denon-uk.custhelp.com/app/answers/detail/a_id/5744/~/heos-control-protocol-\(cli\))

# Notice

This unsponsored software is provided, subject to a MIT license, unofficially and independently of Sound United, LLC, its affiliates, subsidiaries and brands (such as HEOS, Denon and any such not listed here).

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