Usage of NRenoiseTools Assembly

Assembly dependencies

To use NRenoiseTools, you must add to your project the NRenoiseTools.dll. The dependencies NRenoiseTools.XmlSerializer.dll (optimized serializers), and ICSharpCode.SharpZipLib.dll (zip support) assemblies must be in the same directory than NRenoiseTools assembly

About the NRenoiseTools class model

The NRenoiseTools class model contains all the types defined in the optimized XSD Renoise Model (See Schema zip in Release). Moreover, NRenoiseTools extends this model and provides additional features :
  • Developping with NRenoiseTools consist mostly in using the Song class and the Instrument class. Starting from these classes, you can access to the data in the song or in an instrument (You don’t have to use subclasses RenoiseSong and RenoiseInstrument. It is used internally by Song and Instrument class when saving or loading this elements).
  • NRenoiseTools adds some useful Load and Save methods in Song class and Instrument class in order to load easily Xrns & Xrni files.
  • The model is also extended to support some inheritance that makes easier the use of the Renoise model. More particularly:
    • PatternTrack, PatternMasterTrack and PatternSendTrack inherit from Track, a newly type only used to facilitate the inheritance and iterate in a song (See SongIterator)
    • RenoiseSong inherits from a new type Song (to make it easier to use and similar with the RenoiseInstrument / Instrument )
    • RenoiseInstrument inherits from Instrument
    • The Sample class inside an Instrument contains a Buffer property that holds the Sample Data (a Wav, Ogg... buffer)
  • A SongIterator class to facilitate iteration in a song. With this class, it’s very easy to iterate on notes, effects in a song with very few lines of code. Xrns2Midi is using this technique.

TODO: Add doc here

Sample : Load and Save of a XRNS / XRNI File

The following code shows you how to use NRenoiseTools to easily Load and Save Xrns and Xrni files. The full content of the song or an instrument is directly accessible from the Song class and Instrument class (Patterns, Tracks, GlobalSongData... etc.).

using NRenoiseTools;
using Song = NRenoiseTools.RenoiseSong;
using Instrument = NRenoiseTools.RenoiseInstrument;

namespace SongInstrumentLoadSaveSample
{
    class Program
    {
        static void Main(string[] args)
        {
            Song song = new Song();
            // Load a XRNS Song from a file
            song.Load("DemoSong - Diggin for Gold.xrns");
            // Save the first instrument of this song to a file
            song.Instruments[0].Save("MyInstrument.xrni");
            // Load previously instrument 
            Instrument instrument = new Instrument();
            instrument.Load("MyInstrument.xrni");
            // Replace the instrument in the song
            song.Instruments[0] = instrument;
            // Save the Song to another XRNS file
            song.Save("NewDemoSong.xrns");
        }
    }
}

Sample : Iterate on a Song

The following code show how it is possible to iterate in a song on Patterns, Tracks, Lines, NoteColumn, EffectColumns using the SongIterator. This technique was used to develop the Xrns2Midi converter.

using System;
using System.IO;
using NRenoiseTools;
using Song = NRenoiseTools.RenoiseSong;
using Instrument = NRenoiseTools.RenoiseInstrument;

namespace SongIteratorSample
{
    class Program
    {
        public class DisplaySong : SongIterator
        {
            public DisplaySong(Song song) : base(song) {}

            public void Display(TextWriter log)
            {
                Iterate(new SongIteratorEvent()
                            {
                                OnBeginSong = delegate
                                                  {
                                                      // Access to current Song
                                                      log.WriteLine("Begin Parse Song Name: <{0}>",
                                                                    Song.GlobalSongData.SongName);
                                                  },
                                OnEndSong = delegate
                                                {
                                                    // Access to current Song
                                                    log.WriteLine("End Parse Song");
                                                },
                                OnBeginPattern = delegate
                                                     {
                                                         // Access to current Pattern
                                                         log.WriteLine("Begin Parse Pattern {0}", PatternIndex);
                                                     },
                                OnEndPattern = delegate
                                                   {
                                                       // Access to current Pattern
                                                       log.WriteLine("End Parse Pattern {0}", PatternIndex);
                                                   },
                                OnBeginTrack = delegate
                                                   {
                                                       // Access to current Track, Pattern
                                                       log.WriteLine("\tBegin Parse Track {0} in Pattern {1}",
                                                                     TrackIndex, PatternIndex);
                                                   },
                                OnEndTrack = delegate
                                                 {
                                                     // Access to current Track, Pattern
                                                     log.WriteLine("\tEnd Parse Track {0} in Pattern {1}",
                                                                   TrackIndex, PatternIndex);
                                                 },
                                OnBeginLine = delegate
                                                  {
                                                      // Access to current Line, Track, Pattern
                                                      log.WriteLine(
                                                          "\t\tBegin Parse Line {0} in Pattern {1} in Track {2}",
                                                          Line.index,
                                                          PatternIndex, TrackIndex);
                                                  },
                                OnEndLine = delegate
                                                {
                                                    // Access to current Line, Track, Pattern
                                                    log.WriteLine("\t\tEnd Parse Line {0} in Pattern {1} in Track {2}",
                                                                  Line.index,
                                                                  PatternIndex, TrackIndex);
                                                },
                                OnNote = delegate
                                             {
                                                 // Access to current NoteColumn, Line, Track, Pattern
                                                 log.WriteLine("\t\t  - Pattern {0} Track {1} Note {2} Instrument {3}",
                                                               PatternIndex,
                                                               TrackIndex, NoteColumn.Note, NoteColumn.Instrument);
                                             },
                                OnEffect = delegate
                                               {
                                                   // Access to current EffectColumn, Line, Track, Pattern
                                                   log.WriteLine(
                                                       "\t\t  - Pattern {0} Track {1} TrackType {2} Effect {3}={4} ",
                                                       PatternIndex,
                                                       TrackIndex, Track.GetType().Name, EffectColumn.Number, EffectColumn.Value);
                                               },
                            });
            }
        }

        static void Main(string[] args)
        {
            Song song = new Song();
            // Load a XRNS Song from a file
            song.Load("DemoSong - Diggin for Gold.xrns");

            DisplaySong displaySongy= new DisplaySong(song);
            displaySongy.Display(Console.Out);

            Console.WriteLine("Press any key");
            Console.ReadKey(true);
        }
    }
}

Last edited Sep 15, 2010 at 9:17 AM by alexandre_mutel, version 4

Comments

No comments yet.