lily/dynamic-performer.cc

   1 /*
   2   This file is part of LilyPond, the GNU music typesetter.
   3
   4   Copyright (C) 2000--2015 Jan Nieuwenhuizen <janneke@gnu.org>
   5
   6   LilyPond 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 3 of the License, or
   9   (at your option) any later version.
  10
  11   LilyPond 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   You should have received a copy of the GNU General Public License
  17   along with LilyPond.  If not, see <http://www.gnu.org/licenses/>.
  18 */
  19
  20 #include "performer.hh"
  21 #include "audio-item.hh"
  22 #include "std-vector.hh"
  23 #include "stream-event.hh"
  24 #include "international.hh"
  25
  26 #include "translator.icc"
  27
  28 class Dynamic_performer : public Performer
  29 {
  30 public:
  31   TRANSLATOR_DECLARATIONS (Dynamic_performer);
  32 protected:
  33   virtual void acknowledge_audio_element (Audio_element_info info);
  34   virtual void finalize ();
  35   void stop_translation_timestep ();
  36   void process_music ();
  37   Real equalize_volume (Real);
  38
  39   void listen_decrescendo (Stream_event *);
  40   void listen_crescendo (Stream_event *);
  41   void listen_absolute_dynamic (Stream_event *);
  42
  43 private:
  44   void close_and_enqueue_span ();
  45   Real compute_departure_volume (Direction depart_dir,
  46                                  Real start_vol,
  47                                  Real end_vol,
  48                                  Real min_vol,
  49                                  Real max_vol);
  50   bool drive_state_machine (Direction next_grow_dir);
  51   // next_vol < 0 means select a target dynamic based on growth direction.
  52   // return actual next volume (computed if not provided)
  53   Real finish_queued_spans (Real next_vol = -1.0);
  54   Real look_up_absolute_volume (SCM dynamicString,
  55                                 Real defaultValue);
  56
  57 private:
  58   // This performer queues a number of dynamic spans waiting for the following
  59   // pattern before computing their volume levels.
  60   //
  61   //  1. the first (de)crescendo, followed by ...
  62   //  2. zero or more spans that either change in the same direction as the
  63   //     first or do not change, followed by ...
  64   //  3. zero or more spans that either change in the opposite direction as the
  65   //     first or do not change
  66   //
  67   // The search may be cut short by an absolute dynamic or the end of the
  68   // context.
  69   enum State
  70   {
  71     STATE_INITIAL = 0, // waiting for a (de)crescendo
  72     STATE_DEPART, // enqueued the first span, gathering same-direction spans
  73     STATE_RETURN // gathering opposite-direction spans
  74   };
  75
  76   struct UnfinishedSpan
  77   {
  78     Audio_span_dynamic *dynamic_;
  79     Direction grow_dir_;
  80
  81     UnfinishedSpan () : dynamic_ (0), grow_dir_ (CENTER) {}
  82   };
  83
  84   struct DynamicQueue
  85   {
  86     vector<UnfinishedSpan> spans_;
  87     // total duration of (de)crescendi (i.e. excluding fixed-volume spans)
  88     Real change_duration_;
  89     Real min_target_vol_;
  90     Real max_target_vol_;
  91
  92     DynamicQueue () : change_duration_ (0) {}
  93
  94     void clear ()
  95     {
  96       spans_.clear ();
  97       change_duration_ = 0;
  98     }
  99
 100     void push_back (const UnfinishedSpan &span,
 101                     Real min_target_vol,
 102                     Real max_target_vol)
 103     {
 104       if (span.grow_dir_ != CENTER)
 105         change_duration_ += span.dynamic_->get_duration ();
 106       min_target_vol_ = min_target_vol;
 107       max_target_vol_ = max_target_vol;
 108       spans_.push_back (span);
 109     }
 110
 111     void set_volume (Real start_vol, Real target_vol);
 112   };
 113
 114 private:
 115   vector<Audio_note *> notes_;
 116   Stream_event *script_event_;
 117   Drul_array<Stream_event *> span_events_;
 118   Direction next_grow_dir_;
 119   Direction depart_dir_;
 120   UnfinishedSpan open_span_;
 121   DynamicQueue depart_queue_;
 122   DynamicQueue return_queue_;
 123   State state_;
 124 };
 125
 126 Dynamic_performer::Dynamic_performer (Context *c)
 127   : Performer (c),
 128     script_event_ (0),
 129     next_grow_dir_ (CENTER),
 130     depart_dir_ (CENTER),
 131     state_ (STATE_INITIAL)
 132 {
 133   span_events_[LEFT]
 134   = span_events_[RIGHT] = 0;
 135 }
 136
 137 void
 138 Dynamic_performer::acknowledge_audio_element (Audio_element_info inf)
 139 {
 140   // Keep track of the notes played in this translation time step so that they
 141   // can be pointed to the current dynamic in stop_translation_timestep.
 142   if (Audio_note *n = dynamic_cast<Audio_note *> (inf.elem_)) {
 143     notes_.push_back (n);
 144   }
 145 }
 146
 147 bool
 148 Dynamic_performer::drive_state_machine (Direction next_grow_dir)
 149 {
 150   switch (state_)
 151     {
 152     case STATE_INITIAL:
 153       if (next_grow_dir != CENTER)
 154         {
 155           state_ = STATE_DEPART;
 156           depart_dir_ = next_grow_dir;
 157         }
 158       break;
 159
 160     case STATE_DEPART:
 161       if (next_grow_dir == -depart_dir_)
 162         state_ = STATE_RETURN;
 163       break;
 164
 165     case STATE_RETURN:
 166       if (next_grow_dir == depart_dir_)
 167         {
 168           state_ = STATE_DEPART;
 169           return true;
 170         }
 171       break;
 172     }
 173
 174   return false;
 175 }
 176
 177 void
 178 Dynamic_performer::close_and_enqueue_span ()
 179 {
 180   if (!open_span_.dynamic_)
 181     programming_error ("no open dynamic span");
 182   else
 183     {
 184       DynamicQueue &dq
 185       = (state_ == STATE_RETURN) ? return_queue_ : depart_queue_;
 186
 187       // Changing equalizer settings in the course of the performance does not
 188       // seem very likely.  This is a fig leaf: Equalize these limit volumes
 189       // now as the required context properties are current.  Note that only
 190       // the limits at the end of the last span in the queue are kept.
 191
 192       // Resist diminishing to silence.  (Idea: Look up "ppppp"
 193       // with dynamicAbsoluteVolumeFunction, however that would yield 0.25.)
 194       const Real min_target = equalize_volume (0.1);
 195       const Real max_target
 196       = equalize_volume (Audio_span_dynamic::MAXIMUM_VOLUME);
 197
 198       open_span_.dynamic_->set_end_moment (now_mom ());
 199       dq.push_back (open_span_, min_target, max_target);
 200     }
 201
 202   open_span_ = UnfinishedSpan ();
 203 }
 204
 205 // Set the starting and target volume for each span in the queue.  The gain
 206 // (loss) of any (de)crescendo is proportional to its share of the total time
 207 // spent changing.
 208 void
 209 Dynamic_performer::DynamicQueue::set_volume (Real start_vol,
 210                                              Real target_vol)
 211 {
 212   const Real gain = target_vol - start_vol;
 213   Real dur = 0; // duration of (de)crescendi processed so far
 214   Real vol = start_vol;
 215   for (vector<UnfinishedSpan>::iterator it = spans_.begin ();
 216        it != spans_.end (); ++it)
 217     {
 218       const Real prev_vol = vol;
 219       if (it->grow_dir_ != CENTER)
 220         {
 221           // grant this (de)crescendo its portion of the gain
 222           dur += it->dynamic_->get_duration ();
 223           vol = start_vol + gain * (dur / change_duration_);
 224         }
 225       it->dynamic_->set_volume (prev_vol, vol);
 226     }
 227 }
 228
 229 // Return a volume which is reasonably distant from the given start and end
 230 // volumes in the given direction, for use as a peak volume in a passage with a
 231 // crescendo followed by a decrescendo (or vice versa).  If the given volumes
 232 // are equal, the returned volume is a also reasonable target volume for a
 233 // single (de)crescendo.
 234 //
 235 // The given minimum and maximum volumes are the allowable dynamic range.
 236 Real
 237 Dynamic_performer::compute_departure_volume (Direction depart_dir,
 238                                              Real start_vol,
 239                                              Real end_vol,
 240                                              Real min_vol,
 241                                              Real max_vol)
 242 {
 243   if (depart_dir == CENTER)
 244     return start_vol;
 245
 246   // Try to find a volume that is a minimum distance from the starting and
 247   // ending volumes.  If the endpoint volumes differ, the nearer one is padded
 248   // less than the farther one.
 249   //
 250   // Example: mf < ... > p.  The legacy behavior was to use a 25% of the
 251   // dynamic range for a (de)crescendo to an unspecified target, and this tries
 252   // to preserve that, but is not possible to use a 25% change for both the
 253   // crescendo and the decrescendo and meet the constraints of this example.
 254   // The decrescendo is a greater change than the crescendo.  Believing that
 255   // 25% is already more than enough for either, pad using 25% for the greater
 256   // change and 7% for the lesser change.
 257   //
 258   // Idea: Use a context property or callback, e.g. the difference between two
 259   // dynamics in dynamicAbsoluteVolumeFunction.  0.25 is the default difference
 260   // between "p" and "ff". (Isn't that rather wide for this purpose?)  0.07 is
 261   // the default difference between "mp" and "mf".
 262   const Real far_padding = 0.25;
 263   const Real near_padding = 0.07;
 264
 265   // If for some reason one of the endpoints is already below the supposed
 266   // minimum or maximum, just accept it.
 267   min_vol = min (min (min_vol, start_vol), end_vol);
 268   max_vol = max (max (max_vol, start_vol), end_vol);
 269
 270   const Real vol_range = max_vol - min_vol;
 271
 272   const Real near_vol = minmax (depart_dir, start_vol, end_vol)
 273                     + depart_dir * near_padding * vol_range;
 274   const Real far_vol = minmax (-depart_dir, start_vol, end_vol)
 275                    + depart_dir * far_padding * vol_range;
 276   const Real depart_vol = minmax (depart_dir, near_vol, far_vol);
 277   return max (min (depart_vol, max_vol), min_vol);
 278 }
 279
 280 Real
 281 Dynamic_performer::finish_queued_spans (Real next_vol)
 282 {
 283   if (depart_queue_.spans_.empty ())
 284     {
 285       programming_error ("no dynamic span to finish");
 286       return next_vol;
 287     }
 288
 289   const Real start_vol = depart_queue_.spans_.front ().dynamic_->get_start_volume ();
 290
 291   if (return_queue_.spans_.empty ())
 292     {
 293       Real depart_vol = next_vol;
 294
 295       // If the next dynamic is not specified or is inconsistent with the
 296       // direction of growth, choose a reasonable target.
 297       if ((next_vol < 0) || (depart_dir_ != sign (next_vol - start_vol)))
 298         {
 299           depart_vol = compute_departure_volume (depart_dir_,
 300                                                  start_vol, start_vol,
 301                                                  depart_queue_.min_target_vol_,
 302                                                  depart_queue_.max_target_vol_);
 303         }
 304
 305       depart_queue_.set_volume (start_vol, depart_vol);
 306       depart_queue_.clear ();
 307       return (next_vol >= 0) ? next_vol : depart_vol;
 308     }
 309   else
 310     {
 311       // If the next dynamic is not specified, return to the starting volume.
 312       const Real return_vol = (next_vol >= 0) ? next_vol : start_vol;
 313       Real depart_vol = compute_departure_volume (depart_dir_,
 314                                                   start_vol, return_vol,
 315                                                   depart_queue_.min_target_vol_,
 316                                                   depart_queue_.max_target_vol_);
 317       depart_queue_.set_volume (start_vol, depart_vol);
 318       depart_queue_.clear ();
 319       return_queue_.set_volume (depart_vol, return_vol);
 320       return_queue_.clear ();
 321       return return_vol;
 322     }
 323 }
 324
 325 Real
 326 Dynamic_performer::equalize_volume (Real volume)
 327 {
 328   /*
 329     properties override default equaliser setting
 330   */
 331   SCM min = get_property ("midiMinimumVolume");
 332   SCM max = get_property ("midiMaximumVolume");
 333   if (scm_is_number (min) || scm_is_number (max))
 334     {
 335       Interval iv (Audio_span_dynamic::MINIMUM_VOLUME,
 336                    Audio_span_dynamic::MAXIMUM_VOLUME);
 337       if (scm_is_number (min))
 338         iv[MIN] = scm_to_double (min);
 339       if (scm_is_number (max))
 340         iv[MAX] = scm_to_double (max);
 341       volume = iv[MIN] + iv.length () * volume;
 342     }
 343   else
 344     {
 345       /*
 346         urg, code duplication:: staff_performer
 347       */
 348       SCM s = get_property ("midiInstrument");
 349
 350       if (!scm_is_string (s))
 351         s = get_property ("instrumentName");
 352
 353       if (!scm_is_string (s))
 354         s = scm_from_ascii_string ("piano");
 355
 356       SCM eq = get_property ("instrumentEqualizer");
 357       if (ly_is_procedure (eq))
 358         s = scm_call_1 (eq, s);
 359
 360       if (is_number_pair (s))
 361         {
 362           Interval iv = ly_scm2interval (s);
 363           volume = iv[MIN] + iv.length () * volume;
 364         }
 365     }
 366   return std::max (std::min (volume, Audio_span_dynamic::MAXIMUM_VOLUME),
 367                    Audio_span_dynamic::MINIMUM_VOLUME);
 368 }
 369
 370 void
 371 Dynamic_performer::finalize ()
 372 {
 373   if (open_span_.dynamic_)
 374     close_and_enqueue_span ();
 375   finish_queued_spans ();
 376 }
 377
 378 Real
 379 Dynamic_performer::look_up_absolute_volume (SCM dynamicString,
 380                                             Real defaultValue)
 381 {
 382   SCM proc = get_property ("dynamicAbsoluteVolumeFunction");
 383
 384   SCM svolume = SCM_EOL;
 385   if (ly_is_procedure (proc))
 386     svolume = scm_call_1 (proc, dynamicString);
 387
 388   return robust_scm2double (svolume, defaultValue);
 389 }
 390
 391 void
 392 Dynamic_performer::process_music ()
 393 {
 394   Real volume = -1;
 395
 396   if (script_event_) // explicit dynamic
 397     {
 398       volume = look_up_absolute_volume (script_event_->get_property ("text"),
 399                                         Audio_span_dynamic::DEFAULT_VOLUME);
 400       volume = equalize_volume (volume);
 401     }
 402   else if (!open_span_.dynamic_) // first time only
 403     {
 404       // Idea: look_up_absolute_volume (ly_symbol2scm ("mf")).
 405       // It is likely to change regtests.
 406       volume = equalize_volume (Audio_span_dynamic::DEFAULT_VOLUME);
 407     }
 408
 409   // end the current span at relevant points
 410   if (open_span_.dynamic_
 411       && (span_events_[START] || span_events_[STOP] || script_event_))
 412     {
 413       close_and_enqueue_span ();
 414       if (script_event_)
 415         {
 416           state_ = STATE_INITIAL;
 417           volume = finish_queued_spans (volume);
 418         }
 419     }
 420
 421   // start a new span so that some dynamic is always in effect
 422   if (!open_span_.dynamic_)
 423     {
 424       if (drive_state_machine (next_grow_dir_))
 425         volume = finish_queued_spans (volume);
 426
 427       // if not known by now, use a default volume for robustness
 428       if (volume < 0)
 429         volume = equalize_volume (Audio_span_dynamic::DEFAULT_VOLUME);
 430
 431       Stream_event *cause
 432       = span_events_[START] ? span_events_[START]
 433         : script_event_ ? script_event_
 434         : span_events_[STOP];
 435
 436       open_span_.dynamic_ = new Audio_span_dynamic (now_mom (), volume);
 437       open_span_.grow_dir_ = next_grow_dir_;
 438       announce_element (Audio_element_info (open_span_.dynamic_, cause));
 439     }
 440 }
 441
 442 void
 443 Dynamic_performer::stop_translation_timestep ()
 444 {
 445   // link notes to the current dynamic
 446   if (!open_span_.dynamic_)
 447     programming_error("no current dynamic");
 448   else
 449     {
 450       for (vector<Audio_note *>::const_iterator ni = notes_.begin ();
 451            ni != notes_.end (); ++ni)
 452         {
 453           (*ni)->dynamic_ = open_span_.dynamic_;
 454         }
 455     }
 456   notes_.clear ();
 457
 458   script_event_ = 0;
 459   span_events_[LEFT]
 460   = span_events_[RIGHT] = 0;
 461   next_grow_dir_ = CENTER;
 462 }
 463
 464 void
 465 Dynamic_performer::listen_decrescendo (Stream_event *r)
 466 {
 467   Direction d = to_dir (r->get_property ("span-direction"));
 468   if (ASSIGN_EVENT_ONCE (span_events_[d], r) && (d == START))
 469     next_grow_dir_ = SMALLER;
 470 }
 471
 472 void
 473 Dynamic_performer::listen_crescendo (Stream_event *r)
 474 {
 475   Direction d = to_dir (r->get_property ("span-direction"));
 476   if (ASSIGN_EVENT_ONCE (span_events_[d], r) && (d == START))
 477     next_grow_dir_ = BIGGER;
 478 }
 479
 480 void
 481 Dynamic_performer::listen_absolute_dynamic (Stream_event *r)
 482 {
 483   ASSIGN_EVENT_ONCE (script_event_, r);
 484 }
 485
 486 void
 487 Dynamic_performer::boot ()
 488 {
 489   ADD_LISTENER (Dynamic_performer, decrescendo);
 490   ADD_LISTENER (Dynamic_performer, crescendo);
 491   ADD_LISTENER (Dynamic_performer, absolute_dynamic);
 492 }
 493
 494 ADD_TRANSLATOR (Dynamic_performer,
 495                 /* doc */
 496                 "",
 497
 498                 /* create */
 499                 "",
 500
 501                 /* read */
 502                 "dynamicAbsoluteVolumeFunction "
 503                 "instrumentEqualizer "
 504                 "midiMaximumVolume "
 505                 "midiMinimumVolume "
 506                 "midiInstrument ",
 507
 508                 /* write */
 509                 ""
 510                );