<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ ModeShape (http://www.modeshape.org)
  ~
  ~ See the COPYRIGHT.txt file distributed with this work for information
  ~ regarding copyright ownership.  Some portions may be licensed
  ~ to Red Hat, Inc. under one or more contributor license agreements.
  ~ See the AUTHORS.txt file in the distribution for a full listing of 
  ~ individual contributors.
  ~
  ~ ModeShape is free software. Unless otherwise indicated, all code in ModeShape
  ~ is licensed to you under the terms of the GNU Lesser General Public License as
  ~ published by the Free Software Foundation; either version 2.1 of
  ~ the License, or (at your option) any later version.
  ~
  ~ ModeShape is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  ~ or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
  ~ for more details.
  ~
  ~ You should have received a copy of the GNU Lesser General Public License
  ~ along with this distribution; if not, write to:
  ~ Free Software Foundation, Inc.
  ~ 51 Franklin Street, Fifth Floor
  ~ Boston, MA  02110-1301  USA
  -->
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"	[
<!ENTITY % CustomDTD SYSTEM "../../custom.dtd">
%CustomDTD;
]>
<chapter id="mp3-sequencer">
  <title>MP3 Sequencer</title>
	      <para>
	      	Another sequencer that is included in ModeShape is the <emphasis role="strong">modeshape-sequencer-mp3</emphasis> sequencer project.
					This sequencer processes MP3 audio files added to a repository and extracts the <ulink url="http://www.id3.org/">ID3</ulink>
				 	metadata for the file, including the track's title, author, album name, year, and comment.
					After extracting this information from the audio files, the sequencer then writes this structure into the repository,
					where it can be further processed, analyzed, searched, navigated, or referenced.
	      </para>
      <sect1>
        <title>Example</title>
	    <para>This sequencer generates a node with the name <code>mp3:metadata</code> below the sequencing target.  That is if
	    the <code>ouputtingTo</code> property from the sequencer configuration is /mp3s/LivinOnAPrayer, the sequencer will output 
	    a node to /mp3s/LivinOnAPrayer/mp3:metadata.
	    </para>
	    <programlisting language="XML" role="XML"><![CDATA[
<mp3:metadata jcr:primaryType="mp3:metadata"
              jcr:mixinTypes="mode:derived"
              mode:derivedAt="2011-05-13T13:12:03.925Z"
              mode:derivedFrom="/files/LOP.mp3"
              mp3:title="Livin' on a Prayer"
              mp3:author="Bon Jovi"
              mp3:album="Slippery When Wet"
              mp3:year="1986"
              mp3:comment="Rock 'n' roll!" />
]]></programlisting>
    <para>
       The CND used by this sequencer is provided below.
    </para>
    <programlisting><![CDATA[
[mp3:metadata] > nt:unstructured, mix:mimeType
  - mp3:title (string)
  - mp3:author (string)
  - mp3:album (string)
  - mp3:year (long)
  - mp3:comment (string)
]]></programlisting>
	      
				<para>
					To use this sequencer, simply include the <code>modeshape-sequencer-mp3</code> JAR and the <ulink url="http://www.jthink.net/jaudiotagger/">JAudioTagger</ulink>
					library in your application and configure the &JcrConfiguration; to use this sequencer using something similar to:
	      </para>
		    <programlisting language="JAVA" role="JAVA"><![CDATA[
JcrConfiguration config = ...

config.sequencer("MP3 Sequencer")
      .usingClass("org.modeshape.sequencer.mp3.Mp3MetadataSequencer")
      .loadedFromClasspath()
      .setDescription("Sequences MP3 files to extract the ID3 tags of the audio file")
      .sequencingFrom("//(*.mp3[*])/jcr:content[@jcr:data]")
      .andOutputtingTo("/mp3s/$1");	
]]></programlisting>
</sect1>
</chapter>
