juce/source/src/audio/midi/juce_MidiFile.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_MIDIFILE_JUCEHEADER__
  27 #define __JUCE_MIDIFILE_JUCEHEADER__
  28
  29 #include "juce_MidiMessageSequence.h"
  30 #include "../../io/streams/juce_InputStream.h"
  31 #include "../../io/streams/juce_OutputStream.h"
  32
  33
  34 //==============================================================================
  35 /**
  36     Reads/writes standard midi format files.
  37
  38     To read a midi file, create a MidiFile object and call its readFrom() method. You
  39     can then get the individual midi tracks from it using the getTrack() method.
  40
  41     To write a file, create a MidiFile object, add some MidiMessageSequence objects
  42     to it using the addTrack() method, and then call its writeTo() method to stream
  43     it out.
  44
  45     @see MidiMessageSequence
  46 */
  47 class JUCE_API  MidiFile
  48 {
  49 public:
  50     //==============================================================================
  51     /** Creates an empty MidiFile object.
  52     */
  53     MidiFile();
  54
  55     /** Destructor. */
  56     ~MidiFile();
  57
  58     //==============================================================================
  59     /** Returns the number of tracks in the file.
  60
  61         @see getTrack, addTrack
  62     */
  63     int getNumTracks() const noexcept;
  64
  65     /** Returns a pointer to one of the tracks in the file.
  66
  67         @returns a pointer to the track, or 0 if the index is out-of-range
  68         @see getNumTracks, addTrack
  69     */
  70     const MidiMessageSequence* getTrack (int index) const noexcept;
  71
  72     /** Adds a midi track to the file.
  73
  74         This will make its own internal copy of the sequence that is passed-in.
  75
  76         @see getNumTracks, getTrack
  77     */
  78     void addTrack (const MidiMessageSequence& trackSequence);
  79
  80     /** Removes all midi tracks from the file.
  81
  82         @see getNumTracks
  83     */
  84     void clear();
  85
  86     /** Returns the raw time format code that will be written to a stream.
  87
  88         After reading a midi file, this method will return the time-format that
  89         was read from the file's header. It can be changed using the setTicksPerQuarterNote()
  90         or setSmpteTimeFormat() methods.
  91
  92         If the value returned is positive, it indicates the number of midi ticks
  93         per quarter-note - see setTicksPerQuarterNote().
  94
  95         It it's negative, the upper byte indicates the frames-per-second (but negative), and
  96         the lower byte is the number of ticks per frame - see setSmpteTimeFormat().
  97     */
  98     short getTimeFormat() const noexcept;
  99
 100     /** Sets the time format to use when this file is written to a stream.
 101
 102         If this is called, the file will be written as bars/beats using the
 103         specified resolution, rather than SMPTE absolute times, as would be
 104         used if setSmpteTimeFormat() had been called instead.
 105
 106         @param ticksPerQuarterNote  e.g. 96, 960
 107         @see setSmpteTimeFormat
 108     */
 109     void setTicksPerQuarterNote (int ticksPerQuarterNote) noexcept;
 110
 111     /** Sets the time format to use when this file is written to a stream.
 112
 113         If this is called, the file will be written using absolute times, rather
 114         than bars/beats as would be the case if setTicksPerBeat() had been called
 115         instead.
 116
 117         @param framesPerSecond      must be 24, 25, 29 or 30
 118         @param subframeResolution   the sub-second resolution, e.g. 4 (midi time code),
 119                                     8, 10, 80 (SMPTE bit resolution), or 100. For millisecond
 120                                     timing, setSmpteTimeFormat (25, 40)
 121         @see setTicksPerBeat
 122     */
 123     void setSmpteTimeFormat (int framesPerSecond,
 124                              int subframeResolution) noexcept;
 125
 126     //==============================================================================
 127     /** Makes a list of all the tempo-change meta-events from all tracks in the midi file.
 128
 129         Useful for finding the positions of all the tempo changes in a file.
 130
 131         @param tempoChangeEvents    a list to which all the events will be added
 132     */
 133     void findAllTempoEvents (MidiMessageSequence& tempoChangeEvents) const;
 134
 135     /** Makes a list of all the time-signature meta-events from all tracks in the midi file.
 136
 137         Useful for finding the positions of all the tempo changes in a file.
 138
 139         @param timeSigEvents        a list to which all the events will be added
 140     */
 141     void findAllTimeSigEvents (MidiMessageSequence& timeSigEvents) const;
 142
 143     /** Returns the latest timestamp in any of the tracks.
 144
 145         (Useful for finding the length of the file).
 146     */
 147     double getLastTimestamp() const;
 148
 149     //==============================================================================
 150     /** Reads a midi file format stream.
 151
 152         After calling this, you can get the tracks that were read from the file by using the
 153         getNumTracks() and getTrack() methods.
 154
 155         The timestamps of the midi events in the tracks will represent their positions in
 156         terms of midi ticks. To convert them to seconds, use the convertTimestampTicksToSeconds()
 157         method.
 158
 159         @returns true if the stream was read successfully
 160     */
 161     bool readFrom (InputStream& sourceStream);
 162
 163     /** Writes the midi tracks as a standard midi file.
 164
 165         @returns true if the operation succeeded.
 166     */
 167     bool writeTo (OutputStream& destStream);
 168
 169     /** Converts the timestamp of all the midi events from midi ticks to seconds.
 170
 171         This will use the midi time format and tempo/time signature info in the
 172         tracks to convert all the timestamps to absolute values in seconds.
 173     */
 174     void convertTimestampTicksToSeconds();
 175
 176
 177 private:
 178     //==============================================================================
 179     OwnedArray <MidiMessageSequence> tracks;
 180     short timeFormat;
 181
 182     void readNextTrack (const uint8* data, int size);
 183     void writeTrack (OutputStream& mainOut, int trackNum);
 184
 185     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (MidiFile);
 186 };
 187
 188
 189 #endif   // __JUCE_MIDIFILE_JUCEHEADER__