Merge c27044d into 7940a1b

.env.example

@@ -0,0 +1,2 @@
+PULSE_SERVER_V13=tcp:192.168.1.4:4317
+PULSE_SERVER_V15=tcp:192.168.1.5:4317

.github/workflows/ci.yml

@@ -22,4 +22,4 @@ jobs:
         node-version: ${{ matrix.node }}
     - run: npm ci
     - run: npm run build --if-present
-    - run: npm test
+    - run: npm run test:unit

.github/workflows/coverage.yml

@@ -0,0 +1,32 @@
+name: coverage
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Checkout project code
+      uses: actions/checkout@v2
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v1
+      with:
+        node-version: '14.x'
+
+    - run: npm ci
+    - run: npm run coverage
+
+    - name: Coveralls
+      uses: coverallsapp/github-action@master
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/deploy.yml → .github/workflows/publish.yml

@@ -1,4 +1,4 @@
-name: deploy
+name: publish
 
 on:
   push:

.gitignore

@@ -108,3 +108,7 @@ build
 
 libs
 cookie
+test/docker/docker-compose.yml
+PAPacket.read.*
+PAPacket.write.*
+PACommand.*

.husky/pre-commit

@@ -0,0 +1,5 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npm run pre-commit
+npm run test:unit

.lintstagedrc

@@ -0,0 +1,5 @@
+{
+	"*.ts": [
+		"npm run lint:fix"
+	],
+}

README.md

@@ -1,3 +1,44 @@
-# pulseaudio
-![CI](https://github.com/tmigone/pulseaudio/workflows/ci/badge.svg) ![NPM](https://img.shields.io/npm/v/@tmigone/pulseaudio.svg?logo=npm&logoColor=fff&label=NPM+package&color=limegreen&link=https://www.npmjs.com/package/@tmigone/pulseaudio)
+# 🎶 @tmigone/pulseaudio 🎶
+ ![NPM](https://img.shields.io/npm/v/@tmigone/pulseaudio.svg?logo=npm&logoColor=fff&label=NPM+package&color=limegreen&link=https://www.npmjs.com/package/@tmigone/pulseaudio) ![CI](https://github.com/tmigone/pulseaudio/workflows/ci/badge.svg) [![Coverage Status](https://coveralls.io/repos/github/tmigone/pulseaudio/badge.svg?branch=refactor)](https://coveralls.io/github/tmigone/pulseaudio?branch=refactor)
 
+`@tmigone/pulseaudio` is a TypeScript based client library for [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio/), the most popular sound server for Linux. This library allows you to easily build clients or applications that interact with a PulseAudio server over it's native protocol, for example media players/recorders, volume control applications, etc.
+
+
+### Features
+- Zero dependency fully typed TypeScript implementation of the PulseAudio client protocol
+- Extensive testing suite (code coverage tracker coming soon)
+- Protocol features: 
+  - authentication - provide authentication data for the server
+  - transport - connect over UNIX domain sockets or TCP sockets
+  - introspection - query, modify and operate on PulseAudio objects like modules, sinks, sources, etc.
+  - events - subscribe to server-side object events like a sink starting playback, etc.
+  - (To be implemented) streams - manage audio playback and recording using Node.js streams
+
+## Installation
+
+Install the library using [npm](https://www.npmjs.com/):
+```bash
+npm install @tmigone/pulseaudio
+```
+
+## Usage
+
+```ts
+import PulseAudio from '@tmigone/pulseaudio'
+
+(async () => {
+  // Connect using tcp or unix socket
+  // const client: PulseAudio = new PulseAudio('unix:/run/pulse/pulseaudio.socket')
+  const client: PulseAudio = new PulseAudio('tcp:192.168.1.10:4317')
+  await client.connect()
+
+  // Set volume of all sinks to 50%
+  const sinks: Sink[] = await client.getSinkList()
+  for (const sink of sinks) {
+    await client.setSinkVolume(sink.index, 50)
+  }
+
+  // Close connection
+  client.disconnect()
+})()
+```

ava-e2e.config.cjs

@@ -0,0 +1,9 @@
+module.exports = {
+  files: ['test/e2e/**/*.spec.ts'],
+  extensions: [
+    'ts'
+  ],
+  require: [
+    'ts-node/register'
+  ]
+}

ava.config.cjs

@@ -0,0 +1,9 @@
+module.exports = {
+  files: ['test/unit/**/*.spec.ts'],
+  extensions: [
+    'ts'
+  ],
+  require: [
+    'ts-node/register'
+  ]
+}

docs/Testing-e2e-setup.md

@@ -0,0 +1,51 @@
+# PulseAudio test environment
+
+Easy setup for testing PulseAudio applications.
+
+Supported PulseAudio versions:
+- PulseAudio v13
+- PulseAudio v15
+
+Supported device types:
+- Raspberry Pi 4
+
+## Prerequisites
+
+1. Register on https://www.balena.io/
+2. Create a fleet on https://dashboard.balena-cloud.com/
+  - Fleet name: `patest` (or any name you like)
+  - Device type: Raspberry Pi 4
+3. Install [balena-cli](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md)
+
+## Usage
+### 1. Create PulseAudio releases
+
+The `test/e2e/deploy-to-balena.sh` script will create and tag releases for all available PulseAudio versions. Run it manually with:
+
+```bash
+chmod +x test/e2e/deploy-to-balena.sh
+./test/e2e/deploy-to-balena.sh
+```
+
+Once the script is done, you should see the releases listed on the `Releases` page on your fleet, notice the tags indicating the PulseAudio version:
+![](../assets/releases.png)
+
+### 2. Provision devices
+
+You'll need to provision one device for each version of PulseAudio you want to setup. Click `Add device` on the `Summary` or `Devices` page on your fleet in balenaCloud and follow the instructions.
+
+### 3. Pin devices to a release
+
+Lastly, you'll need to pin the devices to the releases you created. Here is a [quick guide](https://www.balena.io/docs/learn/deploy/release-strategy/release-policy/#pin-device-to-a-release) on how to do it. Make sure you pin one device for each different release (PulseAudio version) you are interested in.
+![](../assets/pin.png)
+
+### 4. Update .env file on your root directory
+
+Update your `.env` file with the IP address of your servers. See `.env.example` for an example:
+
+```
+PULSE_SERVER_V13=tcp:192.168.1.4:4317
+PULSE_SERVER_V15=tcp:192.168.1.5:4317
+```
+
+

docs/Testing-generate-fixture.md

@@ -0,0 +1,14 @@
+# Generate fixture data for tests
+
+To get fixture data for a given command:
+1) Make sure you have a working PulseAudio v13 server. See [Testing-e2e-setup.md](Testing-e2e-setup.md)
+2) Edit `test/e2e/getFixtureData.ts`, find the line where the client invokes a command and change it to your command:
+```
+const data = await client.<yourCommand>(<params>)
+```
+3) Run `ts-node test/e2e/getFixtureData.ts`. This will create several files of interest: `PAPacket.write.*` and `PACommand.data`.
+4) Create the fixture file `test/fixtures/<command_type>/<command>.json` with the following keys:
+- "queryParameters" --> Array. Parameters passed to the command (`<params>`). Prepend a `2` to the list, corresponding to the test `requestId`.
+- "queryBuffer" --> String (hex buffer). The request sent to the PA server. Can be found in `PAPacket.write.buffer`.
+- "replyBuffer" --> String (hex buffer). The response received from the PA server. Can be found in `PAPacket.read.buffer`.
+- "replyObject" --> Object. The parsed response received from the PA server. Can be found in `PACommand.data`.

docs/Testing.md

@@ -0,0 +1,9 @@
+# Testing
+
+Unit tests:
+- run against data snapshots (`test/fixtures`) extracted from requests made to a PulseAudio server running v13
+- run with `npm run test`
+
+E2E tests:
+- run against live PulseAudio servers, either v13 or v15. See [Testing-e2e-setup.md](Testing-e2e-setup.md) for instructions on how to setup the environment.
+- run with `npm run test:e2e`