@fonoster/streams 0.6.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Fonoster Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+streams
+=================
+
+[![Streams](https://img.shields.io/badge/streams-api-brightgreen.svg)](https://fonoster.com)
+[![Version](https://img.shields.io/npm/v/@fonoster/streams.svg)](https://npmjs.org/package/@fonoster/streams)
+[![Downloads/week](https://img.shields.io/npm/dw/@fonoster/streams.svg)](https://npmjs.org/package/@fonoster/streams)
+[![License](https://img.shields.io/npm/l/@fonoster/streams.svg)](https://github.com/fonoster/fonoster/blob/main/package.json)
+
+This is a NodeJS implementation of the AudioSocket protocol, which is a simple protocol for accessing bidirectional audio streams from Asterisk.
+
+* [Installation](#installation)
+* [Example](#example)
+* [APIs](#apis)
+
+## Installation
+
+```sh-session
+$ npm install --save @fonoster/streams
+```
+
+## Example
+
+While the AudioSocket is a utility for Fonoster Streams, it can be used as a standalone module. To use this library with Asterisk, you must configure your dialplan to use the `AudioSocket` application. Here is an example of how to use the AudioSocket with Asterisk:
+
+```
+exten = 100,1,Verbose("Call to AudioSocket via Dialplan Application")
+ same = n,Answer()
+ same = n,AudioSocket(40325ec2-5efd-4bd3-805f-53576e581d13,server.example.com:9092)
+ same = n,Hangup()
+```
+
+Or with the `Dial` application:
+
+```
+exten = 100,1,Verbose("Call to AudioSocket via Dialplan Application")
+ same = n,Answer()
+ same = n,Dial(SIP/100,30,A(AudioSocket(40325ec2-5efd-4bd3-805f-53576e581d13,server.example.com:9092)))
+ same = n,Hangup()
+```
+
+Connecting to the AudioSocket server using ARI with the `externalMedia` endpoint is also possible. You must ensure you set the transport to `TCP` the UUID in the data field. 
+
+> Currently, the payload towards Asterisk is limited to signed linear, 16-bit, 8kHz, mono PCM (little-endian). However, the payload from Asterisk can be changed with the `format` parameter when using ARI.
+
+Once Asterisk is configured, you can use the `AudioSocket` class to create a server that listens for connections. Here is an example of how to use the `AudioSocket` class:
+
+```js
+const { AudioSocket } = require("@fonoster/streams");
+
+const audioSocket = new AudioSocket();
+
+audioSocket.onConnection(async (req, res) => {
+  console.log("new connection from:", req.ref);
+
+  res.on("data", (data) => {
+     // Do something with the audio data
+  );
+
+  res.on("end", () => {
+     // Do something when the stream ends
+  });
+
+  res.on("error", (err) => {
+     // Do something when an error occurs
+  });
+
+  // Utility for playing audio files
+  await res.play("/path/to/audio/file");
+});
+
+audioSocket.listen(9092, () => {
+  console.log("server listening on port 9092");
+});
+```
+
+## APIs
+
+* [`AudioSocket`](#AudioSocket)
+* [`AudioStream`](#AudioStream)
+
+
+<a name="AudioSocket"></a>
+
+## AudioSocket
+A NodeJS implementation of the AudioSocket protocol. The AudioSocket protocol is
+a simple protocol for streaming audio from Asterisk to a NodeJS application. The protocol is
+based on the I/O multiplexing model and uses
+
+**Kind**: global class  
+**See**: AudioStream  
+
+* [AudioSocket](#AudioSocket)
+    * [new AudioSocket()](#new_AudioSocket_new)
+    * [.onConnection(handler)](#AudioSocket+onConnection)
+    * [.close()](#AudioSocket+close)
+
+<a name="new_AudioSocket_new"></a>
+
+### new AudioSocket()
+Constructs a new AudioSocket instance.
+
+**Example**  
+```js
+const { AudioSocket } = require("@fonoster/streams");
+
+const audioSocket = new AudioSocket();
+
+audioSocket.onConnection(async (req, res) => {
+  console.log("new connection from:", req.ref);
+
+  res.on("data", (data) => {
+     // Do something with the audio data
+  );
+
+  res.on("end", () => {
+     // Do something when the stream ends
+  });
+
+  res.on("error", (err) => {
+     // Do something when an error occurs
+  });
+
+  // Utility for playing audio files
+  await res.play("/path/to/audio/file");
+});
+
+audioSocket.listen(9092, () => {
+  console.log("server listening on port 9092");
+});
+```
+<a name="AudioSocket+onConnection"></a>
+
+### audioSocket.onConnection(handler)
+Sets the handler to be called when a new connection is established.
+
+**Kind**: instance method of [<code>AudioSocket</code>](#AudioSocket)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | <code>function</code> | The handler to call when a new connection is established |
+
+**Example**  
+```js
+audioSocket.onConnection(async (req, res) => {
+  console.log("new connection from:", req.ref);
+
+  await res.play("/path/to/audio/file");
+});
+```
+<a name="AudioSocket+close"></a>
+
+### audioSocket.close()
+Closes the server and stops listening for connections.
+
+**Kind**: instance method of [<code>AudioSocket</code>](#AudioSocket)  
+
+<a name="AudioStream"></a>
+
+## AudioStream
+Object representing a stream of bidirectional audio data and control messages.
+
+**Kind**: global class  
+
+* [AudioStream](#AudioStream)
+    * [new AudioStream(stream, socket)](#new_AudioStream_new)
+    * [.write(data)](#AudioStream+write)
+    * [.hangup()](#AudioStream+hangup)
+    * [.play(filePath)](#AudioStream+play) ⇒ <code>Promise.&lt;void&gt;</code>
+    * [.onData(callback)](#AudioStream+onData) ⇒ [<code>AudioStream</code>](#AudioStream)
+    * [.onClose(callback)](#AudioStream+onClose) ⇒ [<code>AudioStream</code>](#AudioStream)
+    * [.onError(callback)](#AudioStream+onError) ⇒ [<code>AudioStream</code>](#AudioStream)
+
+<a name="new_AudioStream_new"></a>
+
+### new AudioStream(stream, socket)
+Creates a new AudioStream.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| stream | <code>Readable</code> | A readable stream |
+| socket | <code>net.Socket</code> | A TCP socket |
+
+<a name="AudioStream+write"></a>
+
+### audioStream.write(data)
+Writes media data to the stream.
+
+**Kind**: instance method of [<code>AudioStream</code>](#AudioStream)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| data | <code>Buffer</code> | The data to write |
+
+<a name="AudioStream+hangup"></a>
+
+### audioStream.hangup()
+Sends a hangup message to the stream and closes the connection.
+
+**Kind**: instance method of [<code>AudioStream</code>](#AudioStream)  
+<a name="AudioStream+play"></a>
+
+### audioStream.play(filePath) ⇒ <code>Promise.&lt;void&gt;</code>
+Utility for playing audio files.
+
+**Kind**: instance method of [<code>AudioStream</code>](#AudioStream)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| filePath | <code>string</code> | The path to the audio file |
+
+<a name="AudioStream+onData"></a>
+
+### audioStream.onData(callback) ⇒ [<code>AudioStream</code>](#AudioStream)
+Adds a listener for the data event.
+
+**Kind**: instance method of [<code>AudioStream</code>](#AudioStream)  
+**Returns**: [<code>AudioStream</code>](#AudioStream) - The AudioStream instance  
+**See**: EventType.DATA  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| callback | <code>function</code> | The callback to be executed |
+
+<a name="AudioStream+onClose"></a>
+
+### audioStream.onClose(callback) ⇒ [<code>AudioStream</code>](#AudioStream)
+Adds a listener for the end event.
+
+**Kind**: instance method of [<code>AudioStream</code>](#AudioStream)  
+**Returns**: [<code>AudioStream</code>](#AudioStream) - The AudioStream instance  
+**See**: EventType.END  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| callback | <code>function</code> | The callback to be executed |
+
+<a name="AudioStream+onError"></a>
+
+### audioStream.onError(callback) ⇒ [<code>AudioStream</code>](#AudioStream)
+Adds a listener for the error event.
+
+**Kind**: instance method of [<code>AudioStream</code>](#AudioStream)  
+**Returns**: [<code>AudioStream</code>](#AudioStream) - The AudioStream instance  
+**See**: EventType.ERROR  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| callback | <code>function</code> | The callback to be executed |
+
+

package/dist/AudioSocket.d.ts

@@ -0,0 +1,81 @@
+import { AudioStream } from "./AudioStream";
+import { StreamRequest } from "./types";
+/**
+ * @classdesc A NodeJS implementation of the AudioSocket protocol. The AudioSocket protocol is
+ * a simple protocol for streaming audio from Asterisk to a NodeJS application. The protocol is
+ * based on the I/O multiplexing model and uses
+ *
+ * @example
+ *
+ * const { AudioSocket } = require("@fonoster/streams");
+ *
+ * const audioSocket = new AudioSocket();
+ *
+ * audioSocket.onConnection(async (req, res) => {
+ *   console.log("new connection from:", req.ref);
+ *
+ *   res.on("data", (data) => {
+ *      // Do something with the audio data
+ *   );
+ *
+ *   res.on("end", () => {
+ *      // Do something when the stream ends
+ *   });
+ *
+ *   res.on("error", (err) => {
+ *      // Do something when an error occurs
+ *   });
+ *
+ *   // Utility for playing audio files
+ *   await res.play("/path/to/audio/file");
+ * });
+ *
+ * audioSocket.listen(9092, () => {
+ *   console.log("server listening on port 9092");
+ * });
+ */
+declare class AudioSocket {
+    private server;
+    private connectionHandler;
+    /**
+     * Constructs a new AudioSocket instance.
+     *
+     * @see AudioStream
+     */
+    constructor();
+    private handleConnection;
+    private handleData;
+    /**
+     * Starts the server listening for connections on the specified port.
+     *
+     * @param {number} port - The port to listen on
+     * @param {() => void} callback - The callback to invoke when the server is listening
+     */
+    listen(port: number, callback?: () => void): void;
+    /**
+     * Starts the server listening for connections on the specified port and bind address.
+     *
+     * @param {number} port - The port to listen on
+     * @param {string} bind - The address to bind to
+     * @param {() => void} callback - The callback to invoke when the server is listening
+     */
+    listen(port: number, bind: string, callback?: () => void): void;
+    /**
+     * Sets the handler to be called when a new connection is established.
+     *
+     * @param {function(StreamRequest, AudioStream): void} handler - The handler to call when a new connection is established
+     * @example
+     *
+     * audioSocket.onConnection(async (req, res) => {
+     *   console.log("new connection from:", req.ref);
+     *
+     *   await res.play("/path/to/audio/file");
+     * });
+     */
+    onConnection(handler: (req: StreamRequest, stream: AudioStream) => void): void;
+    /**
+     * Closes the server and stops listening for connections.
+     */
+    close(): void;
+}
+export { AudioSocket };

package/dist/AudioSocket.js

@@ -0,0 +1,161 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AudioSocket = void 0;
+/* eslint-disable no-dupe-class-members */
+/*
+ * Copyright (C) 2024 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * 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.
+ */
+const net_1 = __importDefault(require("net"));
+const stream_1 = require("stream");
+const logger_1 = require("@fonoster/logger");
+const AudioSocketError_1 = require("./AudioSocketError");
+const AudioStream_1 = require("./AudioStream");
+const nextMessage_1 = require("./nextMessage");
+const types_1 = require("./types");
+const logger = (0, logger_1.getLogger)({ service: "streams", filePath: __filename });
+/**
+ * @classdesc A NodeJS implementation of the AudioSocket protocol. The AudioSocket protocol is
+ * a simple protocol for streaming audio from Asterisk to a NodeJS application. The protocol is
+ * based on the I/O multiplexing model and uses
+ *
+ * @example
+ *
+ * const { AudioSocket } = require("@fonoster/streams");
+ *
+ * const audioSocket = new AudioSocket();
+ *
+ * audioSocket.onConnection(async (req, res) => {
+ *   console.log("new connection from:", req.ref);
+ *
+ *   res.on("data", (data) => {
+ *      // Do something with the audio data
+ *   );
+ *
+ *   res.on("end", () => {
+ *      // Do something when the stream ends
+ *   });
+ *
+ *   res.on("error", (err) => {
+ *      // Do something when an error occurs
+ *   });
+ *
+ *   // Utility for playing audio files
+ *   await res.play("/path/to/audio/file");
+ * });
+ *
+ * audioSocket.listen(9092, () => {
+ *   console.log("server listening on port 9092");
+ * });
+ */
+class AudioSocket {
+    /**
+     * Constructs a new AudioSocket instance.
+     *
+     * @see AudioStream
+     */
+    constructor() {
+        this.connectionHandler = null;
+        this.server = net_1.default.createServer(this.handleConnection.bind(this));
+    }
+    handleConnection(socket) {
+        logger.info("client connected");
+        const asStream = new stream_1.Readable({ read() { } });
+        const audioStream = new AudioStream_1.AudioStream(asStream, socket);
+        socket.on(types_1.EventType.DATA, (data) => this.handleData(data, asStream, audioStream));
+        socket.on(types_1.EventType.END, () => asStream.emit(types_1.EventType.END));
+        socket.on(types_1.EventType.ERROR, (err) => {
+            logger.error("socket error:", err);
+            asStream.emit(types_1.EventType.ERROR, err);
+        });
+    }
+    handleData(data, asStream, audioStream) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const stream = new stream_1.Readable({ read() { } });
+            stream.push(data);
+            stream.push(null); // End of the stream
+            try {
+                const message = yield (0, nextMessage_1.nextMessage)(stream);
+                switch (message.getKind()) {
+                    case types_1.MessageType.ID:
+                        if (this.connectionHandler) {
+                            this.connectionHandler({ ref: message.getId() }, audioStream);
+                        }
+                        else {
+                            logger.warn("no connection handler set");
+                        }
+                        break;
+                    case types_1.MessageType.SLIN:
+                    case types_1.MessageType.SILENCE:
+                        asStream.emit(types_1.EventType.DATA, message.getPayload());
+                        break;
+                    case types_1.MessageType.HANGUP:
+                        asStream.emit(types_1.EventType.END);
+                        break;
+                    case types_1.MessageType.ERROR:
+                        asStream.emit(types_1.EventType.ERROR, new AudioSocketError_1.AudioSocketError(message.getErrorCode()));
+                        break;
+                    default:
+                        logger.warn("unknown message type");
+                        break;
+                }
+            }
+            catch (err) {
+                logger.error("error processing message:", err);
+            }
+        });
+    }
+    listen(port, bindOrCallback, callback) {
+        const bind = typeof bindOrCallback === "string" ? bindOrCallback : "0.0.0.0";
+        const cb = typeof bindOrCallback === "function" ? bindOrCallback : callback;
+        this.server.listen(port, bind, cb);
+    }
+    /**
+     * Sets the handler to be called when a new connection is established.
+     *
+     * @param {function(StreamRequest, AudioStream): void} handler - The handler to call when a new connection is established
+     * @example
+     *
+     * audioSocket.onConnection(async (req, res) => {
+     *   console.log("new connection from:", req.ref);
+     *
+     *   await res.play("/path/to/audio/file");
+     * });
+     */
+    onConnection(handler) {
+        this.connectionHandler = handler;
+    }
+    /**
+     * Closes the server and stops listening for connections.
+     */
+    close() {
+        this.server.close();
+    }
+}
+exports.AudioSocket = AudioSocket;

package/dist/AudioSocketError.d.ts

@@ -0,0 +1,7 @@
+import { ErrorCode } from "./types";
+declare class AudioSocketError extends Error {
+    errorCode: ErrorCode;
+    constructor(errorCode: ErrorCode);
+    static getMessageFromCode(errorCode: ErrorCode): string;
+}
+export { AudioSocketError };

package/dist/AudioSocketError.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AudioSocketError = void 0;
+/*
+ * Copyright (C) 2024 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * 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.
+ */
+const types_1 = require("./types");
+class AudioSocketError extends Error {
+    constructor(errorCode) {
+        super(AudioSocketError.getMessageFromCode(errorCode));
+        this.errorCode = errorCode;
+        this.name = "AudioSocketError";
+    }
+    static getMessageFromCode(errorCode) {
+        switch (errorCode) {
+            case types_1.ErrorCode.NONE:
+                return "No error";
+            case types_1.ErrorCode.AST_HANGUP:
+                return "Asterisk hangup";
+            case types_1.ErrorCode.AST_FRAME_FORWARDING:
+                return "Asterisk frame forwarding";
+            case types_1.ErrorCode.AST_MEMORY:
+                return "Asterisk memory";
+            default:
+                return "Unknown error";
+        }
+    }
+}
+exports.AudioSocketError = AudioSocketError;

package/dist/AudioStream.d.ts

@@ -0,0 +1,61 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import * as net from "net";
+import { Readable } from "stream";
+/**
+ * @classdesc Object representing a stream of bidirectional audio data and control messages.
+ */
+declare class AudioStream {
+    private stream;
+    private socket;
+    /**
+     * Creates a new AudioStream.
+     *
+     * @param {Readable} stream - A readable stream
+     * @param {net.Socket} socket - A TCP socket
+     */
+    constructor(stream: Readable, socket: net.Socket);
+    /**
+     * Writes media data to the stream.
+     *
+     * @param {Buffer} data - The data to write
+     */
+    write(data: Buffer): void;
+    /**
+     * Sends a hangup message to the stream and closes the connection.
+     */
+    hangup(): void;
+    /**
+     * Utility for playing audio files.
+     *
+     * @param {string} filePath - The path to the audio file
+     * @return {Promise<void>}
+     */
+    play(filePath: string): Promise<void>;
+    /**
+     * Adds a listener for the data event.
+     *
+     * @param {function(Buffer): void} callback - The callback to be executed
+     * @return {AudioStream} The AudioStream instance
+     * @see EventType.DATA
+     */
+    onData(callback: (data: Buffer) => void): this;
+    /**
+     * Adds a listener for the end event.
+     *
+     * @param {function(): void} callback - The callback to be executed
+     * @return {AudioStream} The AudioStream instance
+     * @see EventType.END
+     */
+    onClose(callback: () => void): this;
+    /**
+     * Adds a listener for the error event.
+     *
+     * @param {function(Error): void} callback - The callback to be executed
+     * @return {AudioStream} The AudioStream instance
+     * @see EventType.ERROR
+     */
+    onError(callback: (err: Error) => void): this;
+}
+export { AudioStream };

package/dist/AudioStream.js

@@ -0,0 +1,147 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AudioStream = void 0;
+/*
+ * Copyright (C) 2024 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * 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.
+ */
+const fs = __importStar(require("fs"));
+const promises_1 = require("node:timers/promises");
+const Message_1 = require("./Message");
+const types_1 = require("./types");
+const MAX_CHUNK_SIZE = 320;
+/**
+ * @classdesc Object representing a stream of bidirectional audio data and control messages.
+ */
+class AudioStream {
+    /**
+     * Creates a new AudioStream.
+     *
+     * @param {Readable} stream - A readable stream
+     * @param {net.Socket} socket - A TCP socket
+     */
+    constructor(stream, socket) {
+        this.stream = stream;
+        this.socket = socket;
+    }
+    /**
+     * Writes media data to the stream.
+     *
+     * @param {Buffer} data - The data to write
+     */
+    write(data) {
+        const buffer = Message_1.Message.createSlinMessage(data);
+        this.socket.write(buffer);
+    }
+    /**
+     * Sends a hangup message to the stream and closes the connection.
+     */
+    hangup() {
+        const buffer = Message_1.Message.createHangupMessage();
+        this.socket.write(buffer);
+        this.socket.end();
+        this.stream.emit(types_1.EventType.END);
+    }
+    /**
+     * Utility for playing audio files.
+     *
+     * @param {string} filePath - The path to the audio file
+     * @return {Promise<void>}
+     */
+    play(filePath) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const fileStream = fs.readFileSync(filePath);
+            let offset = 0;
+            // eslint-disable-next-line no-loops/no-loops
+            while (offset < fileStream.length) {
+                const sliceSize = Math.min(fileStream.length - offset, MAX_CHUNK_SIZE);
+                const slicedChunk = fileStream.subarray(offset, offset + sliceSize);
+                const buffer = Message_1.Message.createSlinMessage(slicedChunk);
+                this.socket.write(buffer);
+                offset += sliceSize;
+                // Wait for 20ms to match the sample rate
+                yield (0, promises_1.setTimeout)(20);
+            }
+        });
+    }
+    /**
+     * Adds a listener for the data event.
+     *
+     * @param {function(Buffer): void} callback - The callback to be executed
+     * @return {AudioStream} The AudioStream instance
+     * @see EventType.DATA
+     */
+    onData(callback) {
+        this.stream.on(types_1.EventType.DATA, callback);
+        return this;
+    }
+    /**
+     * Adds a listener for the end event.
+     *
+     * @param {function(): void} callback - The callback to be executed
+     * @return {AudioStream} The AudioStream instance
+     * @see EventType.END
+     */
+    onClose(callback) {
+        this.stream.on(types_1.EventType.END, callback);
+        return this;
+    }
+    /**
+     * Adds a listener for the error event.
+     *
+     * @param {function(Error): void} callback - The callback to be executed
+     * @return {AudioStream} The AudioStream instance
+     * @see EventType.ERROR
+     */
+    onError(callback) {
+        this.stream.on(types_1.EventType.ERROR, callback);
+        return this;
+    }
+}
+exports.AudioStream = AudioStream;

package/dist/Message.d.ts

@@ -0,0 +1,16 @@
+/// <reference types="node" />
+import { ErrorCode, MessageType } from "./types";
+declare class Message {
+    private data;
+    constructor(data: Buffer);
+    getContentLength(): number;
+    getKind(): MessageType;
+    getErrorCode(): ErrorCode;
+    getPayload(): Buffer | null;
+    getId(): string;
+    private static createMessage;
+    static createHangupMessage(): Buffer;
+    static createIDMessage(id: string): Buffer;
+    static createSlinMessage(data: Buffer): Buffer;
+}
+export { Message };

package/dist/Message.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Message = void 0;
+/*
+ * Copyright (C) 2024 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * 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.
+ */
+const uuid_1 = require("uuid");
+const types_1 = require("./types");
+class Message {
+    constructor(data) {
+        this.data = data;
+    }
+    getContentLength() {
+        return this.data.length >= types_1.MINIMUM_MESSAGE_LENGTH
+            ? this.data.readUInt16BE(1)
+            : 0;
+    }
+    getKind() {
+        return this.data.length > 0 ? this.data[0] : types_1.MessageType.ERROR;
+    }
+    getErrorCode() {
+        if (this.getKind() !== types_1.MessageType.ERROR)
+            return types_1.ErrorCode.NONE;
+        return this.data.length >= 4
+            ? this.data[types_1.MINIMUM_MESSAGE_LENGTH]
+            : types_1.ErrorCode.UNKNOWN;
+    }
+    getPayload() {
+        const size = this.getContentLength();
+        return size > 0 ? this.data.subarray(types_1.MINIMUM_MESSAGE_LENGTH) : null;
+    }
+    getId() {
+        if (this.getKind() !== types_1.MessageType.ID) {
+            throw new Error(`Wrong message type ${this.getKind()}`);
+        }
+        return (0, uuid_1.stringify)(this.getPayload());
+    }
+    static createMessage(type, data) {
+        if (data.length > types_1.MAXIMUM_MESSAGE_LENGTH) {
+            throw new Error("Message too large");
+        }
+        const out = Buffer.alloc(types_1.MINIMUM_MESSAGE_LENGTH + data.length);
+        out[0] = type;
+        out.writeUInt16BE(data.length, 1);
+        data.copy(out, types_1.MINIMUM_MESSAGE_LENGTH);
+        return out;
+    }
+    static createHangupMessage() {
+        return Buffer.from([types_1.MessageType.HANGUP, 0x00, 0x00]);
+    }
+    static createIDMessage(id) {
+        const idBuffer = Buffer.from((0, uuid_1.parse)(id));
+        return this.createMessage(types_1.MessageType.ID, idBuffer);
+    }
+    static createSlinMessage(data) {
+        return this.createMessage(types_1.MessageType.SLIN, data);
+    }
+}
+exports.Message = Message;

package/dist/example.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/example.js

@@ -0,0 +1,60 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/*
+ * Copyright (C) 2024 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * 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.
+ */
+const logger_1 = require("@fonoster/logger");
+const _1 = require(".");
+const logger = (0, logger_1.getLogger)({ service: "streams", filePath: __filename });
+const PORT = 9092;
+const audioSocket = new _1.AudioSocket();
+function connectionHandler(req, stream) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { ref } = req;
+        logger.verbose("new connection", { ref });
+        // Do something with the data (e.g. save it to a file, or send it to a transcription service)
+        // stream.onData((_data) => { /* save on a file or send to a transcription service */ });
+        stream.onClose(() => {
+            logger.verbose("stream closed");
+        });
+        stream.onError((err) => {
+            logger.error("stream error", err);
+        });
+        const filePath = process.cwd() + "/etc/sounds/test.sln";
+        logger.verbose("playing sound", { filePath });
+        yield stream.play(filePath);
+        // Hangup the stream after 10 seconds
+        setTimeout(() => __awaiter(this, void 0, void 0, function* () {
+            logger.verbose("hangin up the stream", { ref });
+            stream.hangup();
+        }), 10000);
+    });
+}
+audioSocket.listen(PORT, () => {
+    logger.info(`audiosocket listening on port ${PORT}`);
+});
+audioSocket.onConnection(connectionHandler);

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./AudioSocket";
+export * from "./AudioStream";
+export * from "./types";

package/dist/index.js

@@ -0,0 +1,37 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/*
+ * Copyright (C) 2024 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * 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.
+ */
+__exportStar(require("./AudioSocket"), exports);
+__exportStar(require("./AudioStream"), exports);
+__exportStar(require("./types"), exports);

package/dist/nextMessage.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="node" />
+import { Readable } from "stream";
+import { Message } from "./Message";
+declare function nextMessage(stream: Readable): Promise<Message>;
+export { nextMessage };

package/dist/nextMessage.js

@@ -0,0 +1,35 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextMessage = void 0;
+const Message_1 = require("./Message");
+const types_1 = require("./types");
+function nextMessage(stream) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const hdr = Buffer.alloc(types_1.MINIMUM_MESSAGE_LENGTH);
+        const bytesRead = (yield stream.read(types_1.MINIMUM_MESSAGE_LENGTH));
+        if (bytesRead.length !== types_1.MINIMUM_MESSAGE_LENGTH) {
+            throw new Error(`Read wrong number of bytes (${bytesRead.length}) for header`);
+        }
+        hdr.set(bytesRead);
+        const payloadLen = hdr.readUInt16BE(1);
+        if (payloadLen < 1)
+            return new Message_1.Message(hdr);
+        const payload = Buffer.alloc(payloadLen);
+        const payloadRead = (yield stream.read(payloadLen));
+        if (payloadRead.length !== payloadLen) {
+            throw new Error(`Read wrong number of bytes (${payloadRead.length}) for payload`);
+        }
+        payload.set(payloadRead);
+        return new Message_1.Message(Buffer.concat([hdr, payload]));
+    });
+}
+exports.nextMessage = nextMessage;

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+declare const MINIMUM_MESSAGE_LENGTH = 3;
+declare const MAXIMUM_MESSAGE_LENGTH = 65535;
+declare enum MessageType {
+    HANGUP = 0,
+    ID = 1,
+    SILENCE = 2,
+    SLIN = 16,
+    ERROR = 255
+}
+declare enum ErrorCode {
+    NONE = 0,
+    AST_HANGUP = 1,
+    AST_FRAME_FORWARDING = 2,
+    AST_MEMORY = 4,
+    UNKNOWN = 255
+}
+declare enum EventType {
+    DATA = "data",
+    END = "end",
+    ERROR = "error"
+}
+type StreamRequest = {
+    ref: string;
+};
+export { StreamRequest, MessageType, EventType, ErrorCode, MINIMUM_MESSAGE_LENGTH, MAXIMUM_MESSAGE_LENGTH };

package/dist/types.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAXIMUM_MESSAGE_LENGTH = exports.MINIMUM_MESSAGE_LENGTH = exports.ErrorCode = exports.EventType = exports.MessageType = void 0;
+/*
+ * Copyright (C) 2024 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * 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.
+ */
+const MINIMUM_MESSAGE_LENGTH = 3;
+exports.MINIMUM_MESSAGE_LENGTH = MINIMUM_MESSAGE_LENGTH;
+const MAXIMUM_MESSAGE_LENGTH = 65535;
+exports.MAXIMUM_MESSAGE_LENGTH = MAXIMUM_MESSAGE_LENGTH;
+var MessageType;
+(function (MessageType) {
+    MessageType[MessageType["HANGUP"] = 0] = "HANGUP";
+    MessageType[MessageType["ID"] = 1] = "ID";
+    MessageType[MessageType["SILENCE"] = 2] = "SILENCE";
+    MessageType[MessageType["SLIN"] = 16] = "SLIN";
+    MessageType[MessageType["ERROR"] = 255] = "ERROR";
+})(MessageType || (exports.MessageType = MessageType = {}));
+var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode[ErrorCode["NONE"] = 0] = "NONE";
+    ErrorCode[ErrorCode["AST_HANGUP"] = 1] = "AST_HANGUP";
+    ErrorCode[ErrorCode["AST_FRAME_FORWARDING"] = 2] = "AST_FRAME_FORWARDING";
+    ErrorCode[ErrorCode["AST_MEMORY"] = 4] = "AST_MEMORY";
+    ErrorCode[ErrorCode["UNKNOWN"] = 255] = "UNKNOWN";
+})(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
+var EventType;
+(function (EventType) {
+    EventType["DATA"] = "data";
+    EventType["END"] = "end";
+    EventType["ERROR"] = "error";
+})(EventType || (exports.EventType = EventType = {}));

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@fonoster/streams",
+  "version": "0.6.1-alpha.0",
+  "description": "Core support for Fonoster Streams",
+  "author": "Pedro Sanders <psanders@fonoster.com>",
+  "homepage": "https://github.com/fonoster/fonoster#readme",
+  "license": "MIT",
+  "main": "dist/index",
+  "types": "dist/index",
+  "directories": {
+    "src": "src",
+    "test": "test"
+  },
+  "scripts": {
+    "prebuild": "rimraf ./dist tsconfig.tsbuildinfo",
+    "build": "tsc -b tsconfig.json",
+    "clean": "rimraf ./dist node_modules tsconfig.tsbuildinfo",
+    "generate:readme": "node ../../.scripts/gen-readme.js"
+  },
+  "dependencies": {
+    "@fonoster/logger": "^0.6.1-alpha.0",
+    "uuid": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/uuid": "^9.0.8"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fonoster/fonoster.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fonoster/fonoster/issues"
+  },
+  "gitHead": "2cdd1508146747550fe048c35d9a010d04f6d3aa"
+}