Skip to content
This repository has been archived by the owner on Aug 6, 2024. It is now read-only.

lacymorrow/xspf-playlist

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

57 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Warning

This project has deprecated dependencies and will receive no new updates.

XSPF Playlist

npm version

Automagic XSPF Playlists

Generate an XSPF playlist file for audio and video files and autofill track details from ID3 tags.

Usage

  $ npm install -g xspf-playlist
  
  $ xspf-playlist 'path/to/media' '{"id3": false}' > playlist.xspf

Place media files into a directory (often named media) and pass it to xspf-playlist. Your media directory will be scanned and exported into an XSPF playlist file automatically. That's it!

Nested directories can be treated as the <artist> and <album> fields with a hierarchy like media/artist/album/track.xxx

xspfPlaylist( media, [, { options }] [, stream] [, callback( err, res ) ])

Accepts either a directory path as a string or an array of track objects as media input. Outputs an XSPF playlist as a sting.

Stream and Callback APIs are provided if true or a function are passed as the last parameter, respectively.

Returns a Promise which resolves to a string by default.

const xspfPlaylist = require('xspf-playlist')

// Scanning a directory
xspfPlaylist('/media')
	.then(console.log)
Or, with a stream
xspfPlaylist('/media', true)
    .pipe(process.stdout)
Or, with a callback
xspfPlaylist('/media', function (error, response) {
	console.log(response)
})
Using options
const xspfPlaylist = require('xspf-playlist')

// Scanning a directory
xspfPlaylist('/media', {'id3': true, 'depth': 0})
	.then(console.log)
Passing an object
xspfPlaylist([
	{
		title: 'file1',
		location: 'file1.mp3'
	},
	...
]).then(console.log)

Tracks will be titled by their filename, sans-extension. Additional creator and album information can be provided by organizing your files into a media/creator/album/title.xxx hierarchy.

An image may be associated with a track by giving it the same filename. To associate one image with an entire folder of tracks, give it the filename artwork. artwork images associate themselves to every sibling and child directory and may be placed anywhere in your media directory hierarchy, so an artwork.jpg in the media directory will act as a global image, filling in for every track that did not already have one provided.

ID3

By default, supported files will be scanned for ID3 tag info which will automatically fill the following track information if present:

  • title
  • artist
  • album
  • year
  • comment
  • track
  • genre
  • picture
  • lyrics
Tag readers
  • ID3v1
  • ID3v2 (with unsynchronisation support!)
  • MP4
  • FLAC

File Types

Supports mp3, wav, and ogg audio and mp4, webm, and ogv video formats.

API

options

options is a valid JSON object.

id3

boolean

By default, the jsmediatags library is used to scan mp3 files and will automatically use the meta information associated with a track, rather than the menu directory hierarchy. This feature can be disabled by passing id3: false in the options parameter.

depth

integer

By default, this tool will scan two directories deep (in order to accomodate media/creator/album/title.ext formats). You can manually set the search depth by passing an integer to the depth option. 0 means no recursion, will only search the supplied directory.

Default options

{"id3": true, "depth": 2}

stream

boolean

If true returns a Stream. if false returns a Promise. Default: false.

callback( error, response )

function

Function to callback when playlist generation is complete. Called with error and response parameters, response is a string.

Related

License

MIT © Lacy Morrow