v2.0.0 (#42)

* guard against empty strings
* write uint16s to buffers
* expose raw frames
* use uint16s to align string encoding
* support multiple images
* move to ESM-only module

.editorconfig

@@ -0,0 +1,7 @@
+root = true
+
+[*]
+end_of_line = lf
+indent_size = 2
+indent_style = space
+trim_trailing_whitespace = true

.eslintrc.json

@@ -0,0 +1,25 @@
+{
+  "extends": [
+    "google",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2017,
+    "sourceType": "module"
+  },
+  "plugins": [
+    "@typescript-eslint"
+  ],
+  "rules": {
+    "no-unused-vars": "off",
+    "indent": "off",
+    "comma-dangle": ["error", "never"],
+    "@typescript-eslint/no-unused-vars": "off",
+    "@typescript-eslint/indent": "off",
+    "@typescript-eslint/interface-name-prefix": "off",
+    "@typescript-eslint/explicit-function-return-type": ["error", {
+      "allowExpressions": true
+    }]
+  }
+}

.gitignore

@@ -1,2 +1,3 @@
-build/
+lib/
+node_modules/
 *.swp

.prettierrc.json

@@ -0,0 +1,10 @@
+{
+  "bracketSpacing": false,
+  "printWidth": 80,
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "none",
+  "useTabs": false,
+  "arrowParens": "always"
+}

.travis.yml

@@ -0,0 +1,5 @@
+language: node_js
+node_js: '10'
+cache: npm
+before_script:
+  - npm run build

README.md

@@ -1,110 +1,97 @@
-id3.js - Javascript ID3 tag parser
-===
+## id3.js - Javascript ID3 tag parser
 
-**id3.js** is a JavaScript library for reading and parsing ID3 tags of MP3 files. **id3.js** can parse both ID3v1 and ID3v2 tags within a browser or Node environment. It also supports reading from local files (Node-only), same-origin URLs (AJAX) and File instances (HTML5 File API).
+**id3.js** is a JavaScript library for reading and parsing ID3 tags of MP3
+files.
 
-AJAX
-===
+It can parse both ID3v1 and ID3v2 tags within a browser or within Node.
 
-```html
-<script src="id3.min.js"></script>
-<script type="text/javascript">
-id3('/audio/track.mp3', function(err, tags) {
-	// tags now contains v1, v2 and merged tags
-});
-</script>
-```
-
-Here the MP3 is being requested by partial AJAX requests, such that only the ID3v1 and ID3v2 tags are read rather than the file as a whole.
+Files can be read from the local disk (Node only), same-origin URLs
+and `File` instances (HTML5 File API).
 
-Local Files
-===
+## Usage
 
-First, install **id3.js** using NPM, the Node package manager.
+Install:
 
 ```
-npm install id3js
+$ npm i -S id3js
 ```
 
-Then use it like so:
+### AJAX
 
-```javascript
-var id3 = require('id3js');
+You may parse ID3 tags of a remote MP3 by URL:
 
-id3({ file: './track.mp3', type: id3.OPEN_LOCAL }, function(err, tags) {
-	// tags now contains your ID3 tags
+```html
+<script type="module">
+import * as id3 from '//unpkg.com/id3js@^2/id3.js';
+
+id3.fromUrl('/audio/track.mp3').then((tags) => {
+  // tags now contains v1, v2 and merged tags
 });
+</script>
 ```
 
-Note that here, the type is set to 'local' directly so that **id3.js** will attempt to read from the local file-system using `fs`.
+This works by sending a `HEAD` request for the file and, based on the response,
+sending subsequent `Range` requests for the ID3 tags.
 
-This will **only work under NodeJS**.
+This is rather efficient as there is no need for the entire file to be
+downloaded.
 
-File API (HTML5)
-===
+### Local Files
 
-```html
-<script src="id3.min.js"></script>
-<script type="text/javascript">
-document.querySelector('input[type="file"]').onchange = function(e) {
-	id3(this.files[0], function(err, tags) {
-		// tags now contains your ID3 tags
-	});
-}
-</script>
+You may parse ID3 tags of a local file in Node:
+
+```ts
+import * as id3 from './node_modules/id3js/id3.js';
+
+id3.fromPath('./test.mp3').then((tags) => {
+  // tags now contains v1, v2 and merged tags
+});
 ```
 
-This will read the data from the File instance using slices, so the entire file is not loaded into memory but rather only the tags.
+**Keep in mind, Node must be run with `--experimental-modules`
+for this to be imported and it cannot be used with `require`.**
 
-Format
-===
+### File inputs (HTML5)
 
-Tags are passed as an object of the following format:
+You may parse ID3 tags of a file input:
 
-```json
-{
-	"artist": "Song artist",
-	"title": "Song name",
-	"album": "Song album",
-	"year": "2013",
-	"v1": {
-		"title": "ID3v1 title",
-		"artist": "ID3v1 artist",
-		"album": "ID3v1 album",
-		"year": "ID3v1 year",
-		"comment": "ID3v1 comment",
-		"track": "ID3v1 track (e.g. 02)",
-		"version": 1.0
-	},
-	"v2": {
-		"artist": "ID3v2 artist",
-		"album": "ID3v2 album",
-		"version": [4, 0]
-	}
-}
-````
+```html
+<input type="file">
+
+<script type="module">
+import * as id3 from '//unpkg.com/id3js@^2/id3.js';
 
-The `artist`, `title`, `album` and `year` properties will always exist, though they will default to null. These particular fields are filled by both ID3v1 and ID3v2, the latter taking the priority.
+document
+  .querySelector('input[type="file"]')
+  .addEventListener('change', async (e) => {
+    const tags = await id3.fromFile(e.currentTarget.files[0]);
+    // tags now contains v1, v2 and merged tags
+  });
+</script>
+```
 
-The `v2` object will contain a variable number of fields, depending on what is defined in the file, whereas the `v1` object will always have the same fields (some of which may be null).
+This will read the data from the File instance using slices,
+so the entire file is not loaded into memory but rather only the tags.
 
-Images
-===
+## Images
 
-On occasion, an MP3 may have an image embedded in the ID3v2 tag. If this is the case, it will be available through `v2.image`. This has a structure like so:
+An MP3 may have images embedded in the ID3 tags. If this is the case,
+they can be accessed through the `tag.images` property and will
+look like so:
 
 ```json
 {
-	"type": "cover-front",
-	"mime": "image/jpeg",
-	"description": null,
-	"data": ArrayBuffer
+  "type": "cover-front",
+  "mime": "image/jpeg",
+  "description": null,
+  "data": ArrayBuffer
 }
 ```
 
-As you can see, the data is provided as an `ArrayBuffer`. To access it, you may use a `DataView` or typed array such as `Uint8Array`.
+As you can see, the data is provided as an `ArrayBuffer`.
+To access it, you may use a `DataView` or typed array such
+as `Uint8Array`.
 
-License
-===
+## License
 
 MIT