2 This file is part of LilyPond, the GNU music typesetter.
4 Copyright (C) 2000--2015 Jan Nieuwenhuizen <janneke@gnu.org>
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.
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.
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/>.
20 #include "performer.hh"
21 #include "audio-item.hh"
22 #include "std-vector.hh"
23 #include "stream-event.hh"
24 #include "international.hh"
26 #include "translator.icc"
28 class Dynamic_performer : public Performer
31 TRANSLATOR_DECLARATIONS (Dynamic_performer);
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);
39 void listen_decrescendo (Stream_event *);
40 void listen_crescendo (Stream_event *);
41 void listen_absolute_dynamic (Stream_event *);
44 void close_and_enqueue_span ();
45 Real compute_departure_volume (Direction depart_dir,
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,
58 // This performer queues a number of dynamic spans waiting for the following
59 // pattern before computing their volume levels.
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
67 // The search may be cut short by an absolute dynamic or the end of the
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
78 Audio_span_dynamic *dynamic_;
81 UnfinishedSpan () : dynamic_ (0), grow_dir_ (CENTER) {}
86 vector<UnfinishedSpan> spans_;
87 // total duration of (de)crescendi (i.e. excluding fixed-volume spans)
88 Real change_duration_;
92 DynamicQueue () : change_duration_ (0) {}
100 void push_back (const UnfinishedSpan &span,
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);
111 void set_volume (Real start_vol, Real target_vol);
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_;
126 Dynamic_performer::Dynamic_performer (Context *c)
129 next_grow_dir_ (CENTER),
130 depart_dir_ (CENTER),
131 state_ (STATE_INITIAL)
134 = span_events_[RIGHT] = 0;
138 Dynamic_performer::acknowledge_audio_element (Audio_element_info inf)
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);
148 Dynamic_performer::drive_state_machine (Direction next_grow_dir)
153 if (next_grow_dir != CENTER)
155 state_ = STATE_DEPART;
156 depart_dir_ = next_grow_dir;
161 if (next_grow_dir == -depart_dir_)
162 state_ = STATE_RETURN;
166 if (next_grow_dir == depart_dir_)
168 state_ = STATE_DEPART;
178 Dynamic_performer::close_and_enqueue_span ()
180 if (!open_span_.dynamic_)
181 programming_error ("no open dynamic span");
185 = (state_ == STATE_RETURN) ? return_queue_ : depart_queue_;
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.
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);
198 open_span_.dynamic_->set_end_moment (now_mom ());
199 dq.push_back (open_span_, min_target, max_target);
202 open_span_ = UnfinishedSpan ();
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
209 Dynamic_performer::DynamicQueue::set_volume (Real start_vol,
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)
218 const Real prev_vol = vol;
219 if (it->grow_dir_ != CENTER)
221 // grant this (de)crescendo its portion of the gain
222 dur += it->dynamic_->get_duration ();
223 vol = start_vol + gain * (dur / change_duration_);
225 it->dynamic_->set_volume (prev_vol, vol);
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.
235 // The given minimum and maximum volumes are the allowable dynamic range.
237 Dynamic_performer::compute_departure_volume (Direction depart_dir,
243 if (depart_dir == CENTER)
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.
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.
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;
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);
270 const Real vol_range = max_vol - min_vol;
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);
281 Dynamic_performer::finish_queued_spans (Real next_vol)
283 if (depart_queue_.spans_.empty ())
285 programming_error ("no dynamic span to finish");
289 const Real start_vol = depart_queue_.spans_.front ().dynamic_->get_start_volume ();
291 if (return_queue_.spans_.empty ())
293 Real depart_vol = next_vol;
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)))
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_);
305 depart_queue_.set_volume (start_vol, depart_vol);
306 depart_queue_.clear ();
307 return (next_vol >= 0) ? next_vol : depart_vol;
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 ();
326 Dynamic_performer::equalize_volume (Real volume)
329 properties override default equaliser setting
331 SCM min = get_property ("midiMinimumVolume");
332 SCM max = get_property ("midiMaximumVolume");
333 if (scm_is_number (min) || scm_is_number (max))
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;
346 urg, code duplication:: staff_performer
348 SCM s = get_property ("midiInstrument");
350 if (!scm_is_string (s))
351 s = get_property ("instrumentName");
353 if (!scm_is_string (s))
354 s = scm_from_ascii_string ("piano");
356 SCM eq = get_property ("instrumentEqualizer");
357 if (ly_is_procedure (eq))
358 s = scm_call_1 (eq, s);
360 if (is_number_pair (s))
362 Interval iv = ly_scm2interval (s);
363 volume = iv[MIN] + iv.length () * volume;
366 return std::max (std::min (volume, Audio_span_dynamic::MAXIMUM_VOLUME),
367 Audio_span_dynamic::MINIMUM_VOLUME);
371 Dynamic_performer::finalize ()
373 if (open_span_.dynamic_)
374 close_and_enqueue_span ();
375 finish_queued_spans ();
379 Dynamic_performer::look_up_absolute_volume (SCM dynamicString,
382 SCM proc = get_property ("dynamicAbsoluteVolumeFunction");
384 SCM svolume = SCM_EOL;
385 if (ly_is_procedure (proc))
386 svolume = scm_call_1 (proc, dynamicString);
388 return robust_scm2double (svolume, defaultValue);
392 Dynamic_performer::process_music ()
396 if (script_event_) // explicit dynamic
398 volume = look_up_absolute_volume (script_event_->get_property ("text"),
399 Audio_span_dynamic::DEFAULT_VOLUME);
400 volume = equalize_volume (volume);
402 else if (!open_span_.dynamic_) // first time only
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);
409 // end the current span at relevant points
410 if (open_span_.dynamic_
411 && (span_events_[START] || span_events_[STOP] || script_event_))
413 close_and_enqueue_span ();
416 state_ = STATE_INITIAL;
417 volume = finish_queued_spans (volume);
421 // start a new span so that some dynamic is always in effect
422 if (!open_span_.dynamic_)
424 if (drive_state_machine (next_grow_dir_))
425 volume = finish_queued_spans (volume);
427 // if not known by now, use a default volume for robustness
429 volume = equalize_volume (Audio_span_dynamic::DEFAULT_VOLUME);
432 = span_events_[START] ? span_events_[START]
433 : script_event_ ? script_event_
434 : span_events_[STOP];
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));
443 Dynamic_performer::stop_translation_timestep ()
445 // link notes to the current dynamic
446 if (!open_span_.dynamic_)
447 programming_error("no current dynamic");
450 for (vector<Audio_note *>::const_iterator ni = notes_.begin ();
451 ni != notes_.end (); ++ni)
453 (*ni)->dynamic_ = open_span_.dynamic_;
460 = span_events_[RIGHT] = 0;
461 next_grow_dir_ = CENTER;
465 Dynamic_performer::listen_decrescendo (Stream_event *r)
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;
473 Dynamic_performer::listen_crescendo (Stream_event *r)
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;
481 Dynamic_performer::listen_absolute_dynamic (Stream_event *r)
483 ASSIGN_EVENT_ONCE (script_event_, r);
487 Dynamic_performer::boot ()
489 ADD_LISTENER (Dynamic_performer, decrescendo);
490 ADD_LISTENER (Dynamic_performer, crescendo);
491 ADD_LISTENER (Dynamic_performer, absolute_dynamic);
494 ADD_TRANSLATOR (Dynamic_performer,
502 "dynamicAbsoluteVolumeFunction "
503 "instrumentEqualizer "