stateful.mjs - File of shame for stateful, impure and otherwise illegal pattern methods Copyright (C) 2025 Strudel contributors - see https://codeberg.org/uzu/strudel/src/branch/main/packages/core/index.mjs This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

7import { register, reify, Pattern } from './pattern.mjs';

Allows you to switch a pattern between different 'timelines'. This is particularly useful when live coding, for example when you want to cue a pattern up to play from its start.

Timelines are specified by number, so that if you had a pattern like n("<0 1 2 3>").s("num").timeline(1) playing, then changed the '1' to '2', it would always align '0' to the nearest cycle. You will likely want to trigger an evaluation a little bit before the cycle starts, to avoid missing events.

After the first use, a timeline will continue with the same 'offset'. That is, if you change a pattern without changing its timeline number, it will stay on that timeline without resetting.

Rather than incrementing a timeline to reset it, it's easier to negate it, e.g. by switching between -2 and 2. This is because when you negate a timeline it will always reset.

You can also pattern the timeline if you want, to create strange resetting patterns. @param {number | Pattern} timeline The timeline that the pattern should play on. @example n("<0 1 2 3>(3,8)") .sound("num") // resets the timeline every two cycles, by negating the timeline. // in a lot of cases this will be edited by a human live coder // rather than patterned! .timeline("<2 -2>".slow(2))

45export const timeline = register(
46  'timeline',
47  function (tpat, pat) {
48    tpat = reify(tpat);
49    const f = function (state) {
50      // Is this called from the scheduler? (rather than from e.g. the visualiser)
51      const scheduler = !!state.controls.cyclist;
52      const timehaps = tpat.query(state);
53      const result = [];
54      for (const timehap of timehaps) {
55        const tlid = timehap.value;
56        let offset;
57        if (tlid === 0) {
58          offset = 0;
59        } else if (tlid in timelines) {
60          offset = timelines[tlid];
61        } else {
62          const timearc = timehap.wholeOrPart();
63          if (!scheduler || state.span.begin.lt(timearc.midpoint())) {
64            offset = timearc.begin;
65          } else {
66            // Sync to end of timearc if we first see it over halfway into its
67            // timespan. Allows 'cuing up' next timeline when live coding.
68            offset = timearc.end;
69          }
70        }
71        if (scheduler) {
72          // update state
73          timelines[tlid] = offset;
74          if (tlid !== 0) {
75            delete timelines[-tlid];
76          }
77        }
78
79        const pathaps = pat
80          .late(offset)
81          .query(state.setSpan(timehap.part))
82          .map((h) => h.setContext(h.combineContext(timehap)));
83        result.push(...pathaps);
84      }
85      return result;
86    };
87    return new Pattern(f, pat._steps);
88  },
89  false,
90);