/// <summary>
/// Sets a root note that will be used by next actions of the builder using
/// <see cref="IntervalDefinition"/> objects.
/// </summary>
/// <param name="rootNoteDefinition">The definition of the root note.</param>
/// <returns>The current <see cref="PatternBuilder"/>.</returns>
/// <remarks>
/// Setting a root note is not an action and thus will not be stored in a pattern.
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="rootNoteDefinition"/> is null.</exception>
public PatternBuilder SetRootNote(NoteDefinition rootNoteDefinition)
{
ThrowIfArgument.IsNull(nameof(rootNoteDefinition), rootNoteDefinition);
_rootNote = rootNoteDefinition;
return(this);
}
/// <summary>
/// Initializes a new instance of the <see cref="Note"/> with the specified
/// note number, length and absolute time.
/// </summary>
/// <param name="noteNumber">Number of the note (60 is middle C).</param>
/// <param name="length">Length of the note in units defined by time division of a MIDI file.</param>
/// <param name="time">Absolute time of the note in units defined by the time division of a MIDI file.</param>
public Note(SevenBitNumber noteNumber, long length, long time)
{
_noteDefinition = NoteDefinition.Get(noteNumber);
Length = length;
Time = time;
}
/// <summary>
/// Adds a note by the specified definition using specified velocity and length.
/// </summary>
/// <param name="noteDefinition">The definition of a note.</param>
/// <param name="length">The length of a note.</param>
/// <param name="velocity">The velocity of a note.</param>
/// <returns>The current <see cref="PatternBuilder"/>.</returns>
/// <exception cref="ArgumentNullException"><paramref name="noteDefinition"/> is null. -or-
/// <paramref name="length"/> is null.</exception>
public PatternBuilder Note(NoteDefinition noteDefinition, ILength length, SevenBitNumber velocity)
{
ThrowIfArgument.IsNull(nameof(noteDefinition), noteDefinition);
ThrowIfArgument.IsNull(nameof(length), length);
return(AddAction(new AddNoteAction(noteDefinition, velocity, length)));
}
/// <summary>
/// Returns a <see cref="NoteDefinition"/> for the specified note number.
/// </summary>
/// <param name="noteNumber">The number of a note (60 is middle C).</param>
/// <returns>A <see cref="NoteDefinition"/> for the <paramref name="noteNumber"/>.</returns>
public static NoteDefinition Get(SevenBitNumber noteNumber)
{
NoteDefinition noteDefinition;
if (!_cache.TryGetValue(noteNumber, out noteDefinition))
{
_cache.Add(noteNumber, noteDefinition = new NoteDefinition(noteNumber));
}
return(noteDefinition);
}
/// <summary>
/// Adds a chord by the specified intervals relative to the root note using specified
/// length and velocity.
/// </summary>
/// <param name="intervalDefinitions">The <see cref="IntervalDefinition"/> objects which define
/// a numbers of half steps from the <paramref name="rootNoteDefinition"/>.</param>
/// <param name="rootNoteDefinition">The definition of the chord's root note.</param>
/// <param name="length">The length of a chord.</param>
/// <param name="velocity">The velocity of a chord.</param>
/// <returns>The current <see cref="PatternBuilder"/>.</returns>
/// <remarks>
/// The result chord will contain the specified root note and notes produced by transposing
/// the <paramref name="rootNoteDefinition"/> by the <paramref name="intervalDefinitions"/>.
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="intervalDefinitions"/> is null. -or-
/// <paramref name="rootNoteDefinition"/> is null. -or- <paramref name="length"/> is null.</exception>
/// <exception cref="ArgumentOutOfRangeException">The number of result chord's note is out of valid range.</exception>
public PatternBuilder Chord(IEnumerable <IntervalDefinition> intervalDefinitions,
NoteDefinition rootNoteDefinition,
ILength length,
SevenBitNumber velocity)
{
ThrowIfArgument.IsNull(nameof(intervalDefinitions), intervalDefinitions);
ThrowIfArgument.IsNull(nameof(rootNoteDefinition), rootNoteDefinition);
return(Chord(new[] { rootNoteDefinition }.Concat(intervalDefinitions.Where(i => i != null)
.Select(i => rootNoteDefinition.Transpose(i))),
length,
velocity));
}
/// <summary>
/// Initializes a new instance of the <see cref="OctaveDefinition"/> with the
/// specified octave number.
/// </summary>
/// <param name="octave">The number of an octave.</param>
/// <exception cref="ArgumentOutOfRangeException"><paramref name="octave"/> is out of valid range.</exception>
private OctaveDefinition(int octave)
{
Debug.Assert(octave >= MinOctaveNumber && octave <= MaxOctaveNumber,
"An octave's number is out of range.");
Number = octave;
_notesDefinitions = Enum.GetValues(typeof(NoteName))
.Cast <NoteName>()
.Where(n => NoteUtilities.IsNoteValid(n, octave))
.ToDictionary(n => n,
n => NoteDefinition.Get(n, octave));
}
/// <summary>
/// Initializes a new instance of the <see cref="Note"/> with the specified
/// Note On and Note Off timed events.
/// </summary>
/// <param name="timedNoteOnEvent">Wrapped <see cref="NoteOnEvent"/>.</param>
/// <param name="timedNoteOffEvent">Wrapped <see cref="NoteOffEvent"/>.</param>
internal Note(TimedEvent timedNoteOnEvent, TimedEvent timedNoteOffEvent)
{
Debug.Assert(timedNoteOnEvent != null);
Debug.Assert(timedNoteOnEvent.Event is NoteOnEvent, "Timed event doesn't wrap a Note On event.");
Debug.Assert(timedNoteOffEvent != null);
Debug.Assert(timedNoteOffEvent.Event is NoteOffEvent, "Timed event doesn't wrap a Note Off event.");
//
var noteOnEvent = (NoteOnEvent)timedNoteOnEvent.Event;
var noteOffEvent = (NoteOffEvent)timedNoteOffEvent.Event;
TimedNoteOnEvent = timedNoteOnEvent;
TimedNoteOffEvent = timedNoteOffEvent;
_noteDefinition = NoteDefinition.Get(noteOnEvent.NoteNumber);
Velocity = noteOnEvent.Velocity;
OffVelocity = noteOffEvent.Velocity;
Channel = noteOnEvent.Channel;
}
/// <summary>
/// Sets note name and octave for current <see cref="Note"/>.
/// </summary>
/// <param name="noteName">Name of the note.</param>
/// <param name="octave">Number of the octave in scientific pitch notation.</param>
/// <remarks>
/// Octave number is specified in scientific pitch notation which means that 4 must be
/// passed to <paramref name="octave"/> to get the number of the middle C.
/// </remarks>
/// <exception cref="InvalidEnumArgumentException"><paramref name="noteName"/> specified an
/// invalid value.</exception>
/// <exception cref="ArgumentException">Note number is out of range for the specified note
/// name and octave.</exception>
public void SetNoteNameAndOctave(NoteName noteName, int octave)
{
_noteDefinition = NoteDefinition.Get(noteName, octave);
}
/// <summary>
/// Adds a chord by the specified intervals relative to the root note using default
/// length and specified velocity.
/// </summary>
/// <param name="intervalDefinitions">The <see cref="IntervalDefinition"/> objects which define
/// a numbers of half steps from the <paramref name="rootNoteDefinition"/>.</param>
/// <param name="rootNoteDefinition">The definition of the chord's root note.</param>
/// <param name="velocity">The velocity of a chord.</param>
/// <returns>The current <see cref="PatternBuilder"/>.</returns>
/// <remarks>
/// The result chord will contain the specified root note and notes produced by transposing
/// the <paramref name="rootNoteDefinition"/> by the <paramref name="intervalDefinitions"/>.
/// To set default note length use <see cref="SetNoteLength(ILength)"/> method. By default the length
/// is 1/4.
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="intervalDefinitions"/> is null. -or-
/// <paramref name="rootNoteDefinition"/> is null.</exception>
/// <exception cref="ArgumentOutOfRangeException">The number of result chord's note is out of valid range.</exception>
public PatternBuilder Chord(IEnumerable <IntervalDefinition> intervalDefinitions,
NoteDefinition rootNoteDefinition,
SevenBitNumber velocity)
{
return(Chord(intervalDefinitions, rootNoteDefinition, _noteLength, velocity));
}
/// <summary>
/// Adds a chord by the specified intervals relative to the root note using specified
/// length and default velocity.
/// </summary>
/// <param name="intervalDefinitions">The <see cref="IntervalDefinition"/> objects which define
/// a numbers of half steps from the <paramref name="rootNoteDefinition"/>.</param>
/// <param name="rootNoteDefinition">The definition of the chord's root note.</param>
/// <param name="length">The length of a chord.</param>
/// <returns>The current <see cref="PatternBuilder"/>.</returns>
/// <remarks>
/// The result chord will contain the specified root note and notes produced by transposing
/// the <paramref name="rootNoteDefinition"/> by the <paramref name="intervalDefinitions"/>.
/// To set default velocity use <see cref="SetVelocity(SevenBitNumber)"/> method. By default the
/// velocity is 100.
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="intervalDefinitions"/> is null. -or-
/// <paramref name="rootNoteDefinition"/> is null. -or- <paramref name="length"/> is null.</exception>
/// <exception cref="ArgumentOutOfRangeException">The number of result chord's note is out of valid range.</exception>
public PatternBuilder Chord(IEnumerable <IntervalDefinition> intervalDefinitions,
NoteDefinition rootNoteDefinition,
ILength length)
{
return(Chord(intervalDefinitions, rootNoteDefinition, length, _velocity));
}
/// <summary>
/// Adds a note by the specified definition using specified velocity and default length.
/// </summary>
/// <param name="noteDefinition">The definition of a note.</param>
/// <param name="velocity">The velocity of a note.</param>
/// <returns>The current <see cref="PatternBuilder"/>.</returns>
/// <remarks>
/// To set default note length use <see cref="SetNoteLength(ILength)"/> method. By default the length
/// is 1/4.
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="noteDefinition"/> is null.</exception>
public PatternBuilder Note(NoteDefinition noteDefinition, SevenBitNumber velocity)
{
return(Note(noteDefinition, _noteLength, velocity));
}
/// <summary>
/// Adds a note by the specified definition using specified length and default velocity.
/// </summary>
/// <param name="noteDefinition">The definition of a note.</param>
/// <param name="length">The length of a note.</param>
/// <returns>The current <see cref="PatternBuilder"/>.</returns>
/// <remarks>
/// To set default velocity use <see cref="SetVelocity(SevenBitNumber)"/> method. By default the
/// velocity is 100.
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="noteDefinition"/> is null. -or-
/// <paramref name="length"/> is null.</exception>
public PatternBuilder Note(NoteDefinition noteDefinition, ILength length)
{
return(Note(noteDefinition, length, _velocity));
}
/// <summary>
/// Adds a note by the specified definition using default length and velocity.
/// </summary>
/// <param name="noteDefinition">The definition of a note.</param>
/// <returns>The current <see cref="PatternBuilder"/>.</returns>
/// <remarks>
/// To set default note length use <see cref="SetNoteLength(ILength)"/> method. By default the length
/// is 1/4. To set default velocity use <see cref="SetVelocity(SevenBitNumber)"/> method. By default the
/// velocity is 100.
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="noteDefinition"/> is null.</exception>
public PatternBuilder Note(NoteDefinition noteDefinition)
{
return(Note(noteDefinition, _noteLength, _velocity));
}
