1/*
    2 *  Prolog part of plsmf: standard MIDI file reading library
    3 *
    4 *  Copyright (C) 2009-2015 Samer Abdallah (Queen Mary University of London; UCL)
    5 *
    6 *  This program is free software; you can redistribute it and/or modify
    7 *  it under the terms of the GNU General Public License as published by
    8 *  the Free Software Foundation; either version 2 of the License, or
    9 *  (at your option) any later version.
   10 *
   11 *  This program is distributed in the hope that it will be useful,
   12 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
   13 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   14 *  GNU General Public License for more details.
   15 */
   16	  
   17:- module(plsmf,
   18	[	smf_new/2
   19   ,  smf_delete/1
   20   ,  smf_read/2		
   21   ,  smf_write/2
   22	,	smf_description/2
   23	,	smf_duration/2
   24	,	smf_duration/3
   25	,	smf_events/2
   26	,	smf_events/3
   27	,	smf_events/4
   28	,	smf_events_between/4
   29   ,  smf_add_events/2
   30   ,  smf_add_events/3
   31   ,  smf_property/2
   32   ,  smf_tempo/3
   33	,	is_smf/1	
   34	]).

Standard MIDI file reading and writing

Types used below:

smf_event ---> msg(nonneg, byte)
             ; msg(nonneg, byte, byte)
             ; msg(nonneg, byte, byte, byte)
             ; text(byte, text)
             ; meta(nonneg, byte, byte, list(byte)).

timeline ---> physical  % time in seconds
            ; metrical. % time in quarter notes
author
- Samer Abdallah
   53:-	use_foreign_library(foreign(plsmf)).
 smf_new(+PPQN:natural, -Ref:smf_blob) is det
Creats a new, empty SMF blob. Data structures will be released when the blob is garbage collected, or when smf_delete/1 is called.
 smf_delete(+Ref:smf_blob) is det
Release data structures associated with an SMF blob.
 smf_read(+File:filename, -Ref:smf_blob) is semidet
Attempts to read standard MIDI file named File and sets Ref to an SMF blob atom which can be used to make further queries about the file.
 smf_write(+Ref:smf_blob, +File:filename) is det
Writes a MIDI file.
 smf_duration(+Ref:smf_blob, +Timeline:oneof([metrical,physical]), -Dur:nonneg) is det
 smf_duration(+Ref:smf_blob, -Dur:nonneg) is det
Returns the duration of the MIDI file in seconds (Timeline=physical) or pulses (Timeline=metrical).
   78smf_duration(Ref,Dur) :- smf_duration(Ref,physical,Dur).
 smf_description(+Ref:smf_blob, -Desc:atom) is det
Sets Desc to an atom containing descriptive text about the MIDI file, inluding the number of tracks and timing information.
 smf_events(+Ref:smf_blob, -Events:list(smf_event)) is det
 smf_events(+Ref:smf_blob, +TL:timeline, -Events:list(smf_event)) is det
smf_events(+Ref:smf_blob, -TL:timeline, -Events:list(smf_event)) is multi
 smf_events(+Ref:smf_blob, Tracks:track_spec, +TL:timeline, -Events:list(smf_event)) is det
Unifies Events with a list containing events in the MIDI file. Not all types of events are handled, but most are. Events are returned in a low-level numeric format containing the bytes in the original MIDI data. See module header for definition of type smf_event.
track_spec ---> all; track(nat).
See also
- smf_events_between/4.
  101smf_events(Ref,Events) :- smf_events(Ref,physical,Events).
  102smf_events(Ref,Timeline,Events) :- smf_events(Ref,all,Timeline,Events).
  103
  104smf_events(Ref,all,Timeline,Events) :- 
  105   timeline(Timeline),
  106   smf_events_without_track(Ref,0,Timeline,-1,-1,Events1),
  107   (  Timeline=physical -> Events=Events1
  108   ;  smf_info(Ref,ppqn,PPQN),
  109      maplist(to_beats(PPQN),Events1,Events)
  110   ).
  111smf_events(Ref,track(T),Timeline,Events) :- 
  112   timeline(Timeline),
  113   smf_property(Ref,tracks(N)), between(1,N,T),
  114   smf_events_without_track(Ref,T,Timeline,-1,-1,Events1),
  115   (  Timeline=physical -> Events=Events1
  116   ;  smf_info(Ref,ppqn,PPQN),
  117      maplist(to_beats(PPQN),Events1,Events)
  118   ).
  119
  120to_beats(PPQN,msg(X,A,B),msg(Y,A,B)) :- Y is X rdiv PPQN.
  121to_beats(PPQN,msg(X,A,B,C),msg(Y,A,B,C)) :- Y is X rdiv PPQN.
  122to_beats(PPQN,msg(X,A,B,C,D),msg(Y,A,B,C,D)) :- Y is X rdiv PPQN.
  123to_beats(PPQN,meta(X,A,B,C),meta(Y,A,B,C)) :- Y is X rdiv PPQN.
 smf_events_between(+Ref:smf_blob, +T1:nonneg, +T2:nonneg, -Events:list(smf_event)) is det
Unifies Events with a list containing events in the MIDI file between the given times T1 and T2. See smf_events/2 for more information about the format of the events list.
  130smf_events_between(Ref,T1,T2,Events) :-
  131   smf_events_without_track(Ref,0,physical,T1,T2,Events).
 is_smf(+Ref) is semidet
Determines whether or not Ref is a MIDI file BLOB as returned by smf_read/2.
 smf_property(+Ref:smf_blob, ?Prop:smf_prop) is multi
Queries properties of a MIDI score: == smf_prop ---> ppqn(nat) % pulses per quarter note ; fps(nat) % frames per second ; tracks(nat) % number of tracks ; resolution(number). ===
  147smf_property(Ref,Prop) :-
  148   member(Key, [ppqn, fps, tracks, resolution]),
  149   Prop =.. [Key,Val],
  150   smf_info(Ref,Key,Val).
 smf_tempo(+Ref:smf_blob, +T:time_spec, -P:tempo_spec) is nondet
Gets the tempo at the given time in a variety of forms.
time_spec ---> seconds(nonneg); pulses(nat).
tempo_spec ---> time(timeline, number)
              ; crochet_duration(nonneg)
              ; crochets_per_minute(nonneg)
              ; time_signature(timesig).
timesig ---> nat/nat.
  163smf_tempo(Ref,seconds(T),Prop) :- smf_tempo(Ref,physical,T,Tempo), tempo_property(Tempo,Prop).
  164smf_tempo(Ref,pulses(T),Prop)  :- smf_tempo(Ref,metrical,T,Tempo), tempo_property(Tempo,Prop).
  165
  166tempo_property(smf_tempo(T,_,_,_,_,_,_),time(metrical,T)).
  167tempo_property(smf_tempo(_,T,_,_,_,_,_),time(physical,T)).
  168tempo_property(smf_tempo(_,_,N,_,_,_,_),crochet_duration(D)) :- D is N rdiv 1000000.
  169tempo_property(smf_tempo(_,_,N,_,_,_,_),crochets_per_minute(D)) :- D is 60000000 rdiv N.
  170tempo_property(smf_tempo(_,_,_,N,D,_,_),time_signature(N/D)).
  171
  172timeline(metrical).
  173timeline(physical).
 smf_add_events(+Ref:smf_blob, +TL:timeline, +Events:list(smf_event)) is det
 smf_add_events(+Ref:smf_blob, +Events:list(smf_event)) is det
Adds a new track containing the given events.
  180smf_add_events(SMF, Events) :- smf_add_events(SMF, physical, Events)