graphico 1.0.0 → 1.1.0

package/README.md

@@ -4,11 +4,20 @@
 
 ## Features
 
-- Simple, object-oriented canvas API for organized graphics programming
-- Easy debugging and extensive configuration
-- Supports multiple canvas layers with transparency
-- Hardware-accelerated graphics and animation
-- User interaction via keyboard or mouse inputs
-- Built-in logic for screenshots and screen recordings
-
-See the examples to learn how to use `graphico`!
+`graphico` boasts several features that make it an extremely versatile package for several project types.
+
+- Simple, **object-oriented canvas API** for organized graphics programming
+- Easy debugging and extensive configuration for **complete customizability**
+- Supports multiple independent **canvas layers** with transparency
+- **Hardware-accelerated graphics** for fast and smooth animation
+- **User interaction** captured via keyboard inputs or mouse movements or clicks
+- Multiple audio tracks supported by system **audio player** with volume, mute, and loop toggle
+- Built-in logic for **screenshots** and **screen recordings** that capture both video and audio
+
+## Caveats
+
+By default, many browsers prevent autoplay, which arguably is a good thing. (Don't you hate it when you have several tabs open and one of them starts making noise?) This security feature blocks API calls to `Canvas.playAudio()` from being called automatically on page load. It needs to be triggered manually (initially) by some form of user interaction; either a key press or a mouse click. After this initial interaction step, calls to `playAudio()` can be performed automatically. If you wanted to have background music looping for a game, it would need to be triggered after pressing the "start" button, for example.
+
+## Learn More
+
+The best way to learn and experience its features is to try it out yourself. See the examples to learn how to use `graphico`!

package/dist/canvas.js

@@ -44,6 +44,18 @@ var Canvas = /** @class */ (function () {
          * Determine whether the client is focused or not
          */
         this.focused = false;
+        /**
+         * Determine whether the user has interacted with this canvas
+         */
+        this.interacted = false;
+        /**
+         * Determine whether audio is allowed or muted
+         */
+        this.muted = false;
+        /**
+         * Contains the list of all active audio elements
+         */
+        this.audios = [];
         this.config = Canvas.setDefaults(options, Canvas.defaults);
         this.width = this.config.width;
         this.height = this.config.height;
@@ -95,6 +107,8 @@ var Canvas = /** @class */ (function () {
             _this.config.mousemove(_this.mouseX, _this.mouseY);
         });
         main.addEventListener('keydown', function (e) {
+            audioContext.resume();
+            _this.interacted = true;
             if (!_this.focused) {
                 return;
             }
@@ -119,6 +133,8 @@ var Canvas = /** @class */ (function () {
             }
         });
         main.addEventListener('mousedown', function (e) {
+            audioContext.resume();
+            _this.interacted = true;
             if (!_this.focused) {
                 return;
             }
@@ -158,11 +174,25 @@ var Canvas = /** @class */ (function () {
             cancelAnimationFrame(_this.animation);
         });
         main.addEventListener('contextmenu', function (e) { return e.preventDefault(); });
-        // Focus on the canvas
-        main.focus();
+        // Initialize audio tracks for recording
+        var stream = new MediaStream(main.captureStream()); // video stream
+        var audioContext = new window.AudioContext();
+        for (var track = 0; track < this.config.numTracks; track++) {
+            var audio = new Audio();
+            var source = audioContext.createMediaElementSource(audio);
+            var destination = audioContext.createMediaStreamDestination();
+            source.connect(destination); // contains the audio stream for recording
+            source.connect(audioContext.destination); // so the user can hear
+            this.audios.push(audio);
+            for (var _i = 0, _a = destination.stream.getAudioTracks(); _i < _a.length; _i++) {
+                var audioTrack = _a[_i];
+                this.log("Adding ".concat(audioTrack.id, " to track ").concat(track, "."));
+                stream.addTrack(audioTrack); // add audio track
+            }
+        }
         // Initialize the media recorder
         var recordPart = [];
-        this.recorder = new MediaRecorder(main.captureStream());
+        this.recorder = new MediaRecorder(stream);
         this.recorder.addEventListener('dataavailable', function (e) {
             _this.log(e.type);
             recordPart.push(e.data);
@@ -181,6 +211,8 @@ var Canvas = /** @class */ (function () {
             _this.keys.splice(0);
             _this.mouseButtons.splice(0);
         });
+        // Focus on the canvas
+        main.focus();
     }
     /**
      * Start the animation.
@@ -252,6 +284,9 @@ var Canvas = /** @class */ (function () {
      * Start recording all layers on the canvas
      */
     Canvas.prototype.startRecording = function () {
+        if (!this.interacted) {
+            throw new Error('The user has not yet interacted with this canvas.');
+        }
         this.recorder.start();
     };
     /**
@@ -262,11 +297,82 @@ var Canvas = /** @class */ (function () {
     };
     /**
      * Determines whether the media recorder is active
-     * @returns `true` if currently recording
+     * @returns True if currently recording
      */
     Canvas.prototype.isRecording = function () {
         return this.recorder.state === 'recording';
     };
+    /**
+     * Play an audio file
+     * @param src The path of the audio file
+     * @param loop Whether to play the audio on loop
+     * @param volume The normalized [0-1] volume
+     * @param track The track number to play on
+     */
+    Canvas.prototype.playAudio = function (src, loop, volume, track) {
+        if (loop === void 0) { loop = false; }
+        if (volume === void 0) { volume = 1; }
+        if (track === void 0) { track = 0; }
+        this.log("Playing audio on track ".concat(track, "."));
+        if (!this.interacted) {
+            throw new Error('The user has not yet interacted with this canvas.');
+        }
+        if (track < 0 || track >= this.config.numTracks) {
+            throw new Error("Track ".concat(track, " is out of range. [0,").concat(this.config.numTracks, ")"));
+        }
+        var audio = this.audios[track];
+        audio.src = src;
+        audio.loop = loop;
+        audio.volume = volume;
+        audio.muted = this.muted;
+        audio.play();
+    };
+    /**
+     * Stop all audio tracks from playing
+     */
+    Canvas.prototype.stopAudio = function (track) {
+        if (track === void 0) { track = -1; }
+        this.log("Stopping audio on track ".concat(track, "."));
+        if (track >= this.config.numTracks) {
+            throw new Error("Track ".concat(track, " is out of range. [0,").concat(this.config.numTracks, ")"));
+        }
+        if (track < 0) {
+            for (var _i = 0, _a = this.audios; _i < _a.length; _i++) {
+                var audio = _a[_i];
+                audio.pause();
+            }
+        }
+        else {
+            this.audios[track].pause();
+        }
+    };
+    /**
+     * Mute all audio
+     */
+    Canvas.prototype.mute = function () {
+        this.muted = true;
+        for (var _i = 0, _a = this.audios; _i < _a.length; _i++) {
+            var audio = _a[_i];
+            audio.muted = this.muted;
+        }
+    };
+    /**
+     * Unmute all audio
+     */
+    Canvas.prototype.unmute = function () {
+        this.muted = false;
+        for (var _i = 0, _a = this.audios; _i < _a.length; _i++) {
+            var audio = _a[_i];
+            audio.muted = this.muted;
+        }
+    };
+    /**
+     * Determines whether audio is muted
+     * @returns True if currently muted
+     */
+    Canvas.prototype.isMuted = function () {
+        return this.muted;
+    };
     /**
      * Draw an object onto the canvas.
      * @param drawable Any drawable object
@@ -274,6 +380,9 @@ var Canvas = /** @class */ (function () {
      */
     Canvas.prototype.draw = function (drawable, layer) {
         if (layer === void 0) { layer = 0; }
+        if (layer < 0 || layer >= this.config.numLayers) {
+            throw new Error("Layer ".concat(layer, " is out of range. [0,").concat(this.config.numLayers, ")"));
+        }
         drawable.draw(this.layers[layer]);
     };
     /**
@@ -282,6 +391,9 @@ var Canvas = /** @class */ (function () {
      */
     Canvas.prototype.clear = function (layer) {
         if (layer === void 0) { layer = -1; }
+        if (layer >= this.config.numLayers) {
+            throw new Error("Layer ".concat(layer, " is out of range. [0,").concat(this.config.numLayers, ")"));
+        }
         if (layer < 0) {
             for (var _i = 0, _a = this.layers; _i < _a.length; _i++) {
                 var layer_1 = _a[_i];
@@ -330,6 +442,7 @@ var Canvas = /** @class */ (function () {
         borderBlur: 'transparent',
         showMouse: true,
         numLayers: 1,
+        numTracks: 1,
         keydown: function () { return; },
         keyup: function () { return; },
         mousemove: function () { return; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphico",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Canvas 2D rendering toolkit for games and visual projects",
   "homepage": "https://npm.nicfv.com/",
   "bin": "",
@@ -23,7 +23,12 @@
     "drawing",
     "art",
     "render",
-    "2D"
+    "2D",
+    "layer",
+    "audio",
+    "track",
+    "animate",
+    "visual"
   ],
   "author": {
     "name": "Nicolas Ventura",

package/types/canvas.d.ts

@@ -55,10 +55,22 @@ export declare class Canvas {
      * Determine whether the client is focused or not
      */
     private focused;
+    /**
+     * Determine whether the user has interacted with this canvas
+     */
+    private interacted;
     /**
      * The media recording object for screen captures
      */
     private readonly recorder;
+    /**
+     * Determine whether audio is allowed or muted
+     */
+    private muted;
+    /**
+     * Contains the list of all active audio elements
+     */
+    private readonly audios;
     /**
      * Create a new canvas with the provided options
      * @param options Configuration options
@@ -104,9 +116,34 @@ export declare class Canvas {
     stopRecording(): void;
     /**
      * Determines whether the media recorder is active
-     * @returns `true` if currently recording
+     * @returns True if currently recording
      */
     isRecording(): boolean;
+    /**
+     * Play an audio file
+     * @param src The path of the audio file
+     * @param loop Whether to play the audio on loop
+     * @param volume The normalized [0-1] volume
+     * @param track The track number to play on
+     */
+    playAudio(src: string, loop?: boolean, volume?: number, track?: number): void;
+    /**
+     * Stop all audio tracks from playing
+     */
+    stopAudio(track?: number): void;
+    /**
+     * Mute all audio
+     */
+    mute(): void;
+    /**
+     * Unmute all audio
+     */
+    unmute(): void;
+    /**
+     * Determines whether audio is muted
+     * @returns True if currently muted
+     */
+    isMuted(): boolean;
     /**
      * Draw an object onto the canvas.
      * @param drawable Any drawable object

package/types/types.d.ts

@@ -42,6 +42,10 @@ export interface Options {
      * The number of layers in this canvas
      */
     readonly numLayers: number;
+    /**
+     * The number of audio tracks
+     */
+    readonly numTracks: number;
     /**
      * Event listener for when a key is pressed
      * @param key The key that was pressed