Merge pull request #17 from ChapelR/v2-dev

v2.1.0

docs/changelog.md

@@ -1,5 +1,13 @@
 ## v2 Series Releases
 
+### v2.1.0
+
+This update mostly addresses a few lingering issues in playlist handling.
+
+- Updated groups to import playlists using the syntax `playlist:listName`. This allows you to use group commands and methods on playlists without having to create a group that's just a mirror of a playlist.
+- Updated playlist methods to be more error resistant and fail more gracefully.
+- Fixed a critical bug in `hal.tracks` sources parsing.
+
 ### v2.0.1
 
 Fixed error in the volume display.

docs/v2.md

@@ -1158,6 +1158,11 @@ Playlists differ from [groups](#defining-groups) in that groups are intended to
 
 A playlist must be given a name and a set of track names, in order.
 
+> [!TIP]
+> **Playlists as groups.**
+>
+> Groups have a few commands and methods playlists don't. If you want to use group commands on a playlist, you don't need to define both a group and a playlist, just pass the group a value list this: `playlist:listName`, to use it as a group.
+
 <!-- tabs:start -->
 
 ##### **Macros**
@@ -1431,23 +1436,14 @@ Methods:
 
 <!-- tabs:end -->
 
-### Other Playlist Commands
-
-There are two other playlist commands: `volume` and `mute`. These commands run the indicated command on each member track in the playlist.
-
-|Command|Description|Macro Example|JavaScript Example|
-|---|---|---|---|
-|`mute`|Mutes or unmutes every track in the playlist.|`(playlist: 'bgm', 'mute', true)`|`A.playlist('bgm').mute(true)`|
-|`volume`|Sets the volume level of every track in the group.|`(group: 'bgm', 'volume', 0.5)`|`A.playlist('bgm').volume(0.5)`|
-
-Generally, groups are the preferred method for handling these sorts of situations, but if all the tracks are already in a playlist, you don't need to create a group just for this. Still, note that playlists are **not** groups&mdash;use groups unless you *need* some sort of ordered playback.
-
 ## Defining Groups
 
 Groups are ways to collect and organize tracks, but should not be confused with [playlists](#defining-playlists). These are designed to allow you to select and control a large number of tracks and do something to them. The methods used by groups are very similar to some of the track methods, but as said, do something to all of them at once.
 
 There are two built-in groups, `playing` and `looping`, that can be used to control all currently playing or looping tracks, respectively. Additionally, you can define your own groups with the macro `(newgroup:)` or the method `A.createGroup()`.
 
+You can also grab playlists and use group methods on them using the syntax `playlist:listName`. For example, if you have a playlist named `bgm`, you could target it with group commands like this `(group: 'playlist:bgm', stop)` or `A.group('playlist:bgm').stop()`.
+
 <!-- tabs:start -->
 
 ##### **Macros**

package.json

@@ -1,6 +1,6 @@
 {
   "name": "harlowe-audio",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Audio library for Twine2/Harlowe2.",
   "main": "gulpfile.js",
   "directories": {

src/js/group.js

@@ -5,6 +5,8 @@
     var Track = A.classes.Track;
     var _extend = A.data._extend;
 
+    var playlistHeader = /(play)?list:(.+)/i;
+
     function createAudioGroup (groupName, trackIDs) {
         if (!trackIDs || !Array.isArray(trackIDs)) {
             trackIDs = [];
@@ -33,6 +35,13 @@
         } else {
             this.members = A.groups[name];
         }
+        if (playlistHeader.test(name)) {
+            var listId = name.match(playlistHeader)[2];
+            if (listId && listId.trim()) {
+                // construct from playlist
+                this.members = A.playlist(listId).tracks;
+            }
+        }
         if (!Array.isArray(this.members)) {
             this.members = [];
             console.error('Could not find members for track group "' + name + '"!');

src/js/list.js

@@ -132,15 +132,26 @@
             return this.looping;
         },
         stop : function () {
-            var track = Track.get(this.current);
-            track.stop();
-            track.$el.off('.playlist');
+            if (this.current && this.isPlaying()) {
+                var track = this.nowPlaying();
+                if (track) {
+                    track.stop();
+                    track.$el.off('.playlist');
+                }
+            } else {
+                this._run('stop');
+            }
             this.current = '';
             this.playing = false;
             return this;
         },
         pause : function () {
-            Track.get(this.current).pause();
+            if (this.current && this.isPlaying()) {
+                var track = this.nowPlaying();
+                if (track) {
+                    track.pause();
+                }
+            }
             this.playing = false;
             return this;
         }

src/js/track.js

@@ -51,6 +51,8 @@
         }
         if (test) {
             sources = [].slice.call(arguments).slice(1);
+        } else if (typeof sources === 'string') {
+            sources = [sources];
         }
         // source mapper
         function mapSources (url) {