man/smfsh-ref.sgml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
   2 <refentry>
   3         <refmeta>
   4                 <refentrytitle>
   5                         <application>smfsh</application>
   6                 </refentrytitle>
   7                 <manvolnum>1</manvolnum>
   8                 <refmiscinfo>smfsh 1.2</refmiscinfo>
   9         </refmeta>
  10         <refnamediv>
  11                 <refname>
  12                         <application>smfsh</application>
  13                 </refname>
  14                 <refpurpose>
  15                         SMF shell
  16                 </refpurpose>
  17         </refnamediv>
  18         <refsynopsisdiv>
  19                 <cmdsynopsis>
  20                         <command>smfsh</command>
  21                         <arg><option>-V</option></arg>
  22                         <arg><replaceable class="parameter">file</replaceable></arg>
  23                 </cmdsynopsis>
  24         </refsynopsisdiv>
  25         <refsect1>
  26                 <title>OPTIONS</title>
  27                 <variablelist>
  28                         <varlistentry>
  29                                 <term>-V</term>
  30                                 <listitem>
  31                                         <para>
  32                                                 Print libsmf version and exit.
  33                                         </para>
  34                                 </listitem>
  35                         </varlistentry>
  36                         <varlistentry>
  37                                 <term><replaceable>file</replaceable></term>
  38                                 <listitem>
  39                                         <para>
  40                                                 Load the file.
  41                                         </para>
  42                                 </listitem>
  43                         </varlistentry>
  44                 </variablelist>
  45         </refsect1>
  46         <refsect1>
  47                 <title>DESCRIPTION</title>
  48                 <para>
  49                         <command>smfsh</command>, an "SMF shell", is an interactive, command-driven frontend
  50                         to libsmf, useful for modifying MIDI files by hand.  It started its life as a debugging aid
  51                         for libsmf.
  52                 </para>
  53                 <para>
  54                         There are four groups of commands: SMF level, track level, event level, and others.
  55                 </para>
  56         </refsect1>
  57
  58         <refsect1>
  59                 <title>SMF LEVEL COMMANDS</title>
  60                 <para>
  61                 SMF level commands display or change properties of smf (i.e. the MIDI file) as a whole.
  62                 </para>
  63                 <variablelist>
  64                         <varlistentry>
  65                                 <term>save <replaceable class="parameter">file</replaceable></term>
  66                                 <listitem>
  67                                         <para>
  68                                                 Save a file.  If the <replaceable class="parameter">file</replaceable>
  69                                                 name is not given, the last file name is used.
  70                                         </para>
  71                                         <para>
  72                                                 Note that this will not ask for confirmation.
  73                                         </para>
  74                                 </listitem>
  75                         </varlistentry>
  76
  77                         <varlistentry>
  78                                 <term>load <replaceable class="parameter">file</replaceable></term>
  79                                 <listitem>
  80                                         <para>
  81                                                 Load a file.  If the <replaceable class="parameter">file</replaceable>
  82                                                 name is not given, the last file name is used.
  83                                         </para>
  84                                         <para>
  85                                                 Instead of using "load", you can pass the file name on the command line.
  86                                         </para>
  87                                 </listitem>
  88                         </varlistentry>
  89                         <varlistentry>
  90                                 <term>ppqn <replaceable class="parameter">new-ppqn</replaceable></term>
  91                                 <listitem>
  92                                         <para>
  93                                                 Show (if used without parameter) or change PPQN (Pulses Per Quarter Note, aka Division).
  94                                         </para>
  95                                 </listitem>
  96                         </varlistentry>
  97                         <varlistentry>
  98                                 <term>format <replaceable class="parameter">new-format</replaceable></term>
  99                                 <listitem>
 100                                         <para>
 101                                                 Show (if used without parameter) or change format.
 102                                         </para>
 103                                 </listitem>
 104                         </varlistentry>
 105                         <varlistentry>
 106                                 <term>tempo</term>
 107                                 <listitem>
 108                                         <para>
 109                                                 Show tempo map.  Tempo map is computed automatically from the SMF contents - to modify
 110                                                 a tempo, just add a Tempo Change event using "add" command.
 111                                         </para>
 112                                 </listitem>
 113                         </varlistentry>
 114                         <varlistentry>
 115                                 <term>length</term>
 116                                 <listitem>
 117                                         <para>
 118                                                 Show total length of the song.  Just like the tempo map, file length is computed
 119                                                 from the SMF contents.
 120                                         </para>
 121                                 </listitem>
 122                         </varlistentry>
 123                 </variablelist>
 124         </refsect1>
 125
 126         <refsect1>
 127                 <title>TRACK LEVEL COMMANDS</title>
 128                 <para>
 129                         Track level commands display or change properties of tracks.  SMF may contain one or more tracks.
 130                 </para>
 131                 <variablelist>
 132                         <varlistentry>
 133                                 <term>tracks</term>
 134                                 <listitem>
 135                                         <para>
 136                                                 Show the list of tracks in the SMF.
 137                                         </para>
 138                                 </listitem>
 139                         </varlistentry>
 140                         <varlistentry>
 141                                 <term>track <replaceable class="parameter">track-number</replaceable></term>
 142                                 <listitem>
 143                                         <para>
 144                                                 Show details of a track (if called without parameter), or select track
 145                                                 with a given number - for example in order to display ("events") the events it contains.
 146                                         </para>
 147                                 </listitem>
 148                         </varlistentry>
 149                         <varlistentry>
 150                                 <term>trackadd</term>
 151                                 <listitem>
 152                                         <para>
 153                                                 Create new track.
 154                                         </para>
 155                                 </listitem>
 156                         </varlistentry>
 157                         <varlistentry>
 158                                 <term>trackrm <replaceable class="parameter">track-number</replaceable></term>
 159                                 <listitem>
 160                                         <para>
 161                                                 Remove the track.  If the track number is not given, this will remove the track currently selected.
 162                                         </para>
 163                                 </listitem>
 164                         </varlistentry>
 165                 </variablelist>
 166         </refsect1>
 167
 168         <refsect1>
 169                 <title>EVENT LEVEL COMMANDS</title>
 170                 <para>
 171                         Event level commands display or change properties of events.  Events are grouped into tracks.
 172                         Track may contain any number of events, including zero.
 173                 </para>
 174                 <variablelist>
 175                         <varlistentry>
 176                                 <term>events</term>
 177                                 <listitem>
 178                                         <para>
 179                                                 Show the list of events in the current track.
 180                                         </para>
 181                                 </listitem>
 182                         </varlistentry>
 183                         <varlistentry>
 184                                 <term>event <replaceable class="parameter">event-number</replaceable></term>
 185                                 <listitem>
 186                                         <para>
 187                                                 Show information about a current event (if used without parameter)
 188                                                 or select the event.
 189                                         </para>
 190                                 </listitem>
 191                         </varlistentry>
 192                         <varlistentry>
 193                                 <term>add <replaceable class="parameter">time-in-seconds</replaceable> <replaceable class="parameter">midi-message-as-hex</replaceable></term>
 194                                 <listitem>
 195                                         <para>
 196                                                 Add new event to the currently selected track.
 197                                         </para>
 198                                 </listitem>
 199                         </varlistentry>
 200                         <varlistentry>
 201                                 <term>rm <replaceable class="parameter">event-number</replaceable></term>
 202                                 <listitem>
 203                                         <para>
 204                                                 Remove the event.  If the event number is not given, this will remove the event currently selected.
 205                                         </para>
 206                                 </listitem>
 207                         </varlistentry>
 208                 </variablelist>
 209         </refsect1>
 210
 211         <refsect1>
 212                 <title>OTHER COMMANDS</title>
 213                 <para>
 214                         There are three commands in the "other" category - "help", "version",
 215                         and "exit".  Their meaning should be self expanatory.
 216                 </para>
 217         </refsect1>
 218 </refentry>
 219