Documentation

Fields

• inst_instrument :: !Inst
   
• inst_qualified :: !InstT.Qualified
   
• inst_common_config :: !Common.Config
   
• inst_backend :: !Backend
   

Fields

• sel_past :: [(ViewId, Sel.Selection)]
   
• sel_future :: [(ViewId, Sel.Selection)]
   

Fields

• hist_state :: !Ui.State
   
• hist_damage :: !Update.UiDamage

  Since track event updates are not caught by diff but recorded by Ui.State, I have to save those too, or else an undo or redo will miss the event changes. TODO ugly, can I avoid this?

  If this HistoryEntry is in the past, these are the updates that took it to the future, not the updates emitted by the cmd itself. If the HistoryEntry is in the future, the updates take it to the past, which are the updated emitted by the cmd. So don't be confused if it looks like a HistoryEntry has the wrong updates.

• hist_names :: ![Text]

  Cmds involved creating this entry.

• hist_commit :: !(Maybe.Maybe GitT.Commit)

  The Commit where this entry was saved. Nothing if the entry is unsaved.

Fields

• state_cmd_names :: ![Text]

  This is cleared after each cmd. A cmd can cons its name on, and the cmd is recorded with the (optional) set of names it returns. Hopefully each cmd has at least one name, since this makes the history more readable. There can be more than one name if the history records several cmds or if one cmd calls another.

• state_suppress_edit :: !(Maybe.Maybe EditMode)

  Suppress history record until the EditMode changes from the given one. This is a bit of a hack so that every keystroke in a raw edit isn't recorded separately.

• state_suppressed :: !(Maybe.Maybe SaveGitT.SaveHistory)

  The Git.Commit in the SaveHistory should definitely be Nothing.

Fields

• hist_keep :: !Int

  Keep this many previous history entries in memory.

• hist_last_commit :: !(Maybe.Maybe GitT.Commit)

  Checkpoints are saved relative to the state at the next checkpoint. So it's important to keep the commit of that checkpoint up to date, otherwise the state and the checkpoints will get out of sync.

Fields

• hist_past :: ![HistoryEntry]
   
• hist_present :: !HistoryEntry

  The present is actually the immediate past. When you undo, the undo itself is actually in the future of the state you want to undo. So another way of looking at it is that you undo from the past to a point further in the past. But since you always require a "recent past" to exist, it's more convenient to break it out and call it the "present". Isn't time travel confusing?

• hist_future :: ![HistoryEntry]
   
• hist_last_cmd :: !(Maybe.Maybe LastCmd)
   

Fields

• inst_calls :: !InstrumentCalls
   
• inst_postproc :: !InstrumentPostproc
   
• inst_cmds :: ![HandlerId]
   
• inst_thru :: !(Maybe.Maybe ThruFunction)

  An optional specialized cmd to write Thru. This is separate from inst_cmds so it can be run wherever the instrument needs special thru, not just in the instrument's note track. This way custom thru works in the pitch track too.

Fields

• wdev_note_addr :: !(Map InputNote.NoteId Patch.Addr)

  NoteId currently playing in each Addr. An Addr may have >1 NoteId.

• wdev_note_key :: !(Map InputNote.NoteId Midi.Key)

  The note id is not guaranteed to have any relationship to the key, so the MIDI NoteOff needs to know what key the MIDI NoteOn used.

• wdev_addr_serial :: !(Map Patch.Addr Serial)

  Map an addr to a number that increases when it's assigned a note. This is used along with wdev_serial to implement addr round-robin.

• wdev_serial :: !Serial

  Next serial number for wdev_addr_serial.

• wdev_last_note_id :: !(Maybe.Maybe InputNote.NoteId)

  Last NoteId seen. This is needed to emit controls (rather than just mapping them from MIDI input) because otherwise there's no way to know to which note they should be assigned.

• wdev_pitch_track :: !(Map InputNote.NoteId (BlockId, Types.TrackNum))

  NoteIds being entered into which pitch tracks. When entering a chord, a PitchChange uses this to know which pitch track to update.

• wdev_addr_inst :: !(Map Patch.Addr Midi.Types.Patch)

  Remember the current patch of each addr. More than one patch or keyswitch can share the same addr, so I need to keep track which one is active to minimize switches.

Fields

• state_edit_mode :: !EditMode

  Edit mode enables various commands that write to tracks.

• state_floating_input :: !Bool

  True if the floating input edit is open.

• state_advance :: Bool

  Whether or not to advance the insertion point after a note is entered.

• state_chord :: Bool

  Chord mode means the note is considered entered when all NoteOffs have been received. While a note is held down, the insertion point will move to the next note track with the same instrument so you can enter chords.

  When chord mode is off, the note is considered entered as soon as its NoteOn is received.

• state_record_velocity :: Bool

  Try to find or create a dynamic track for to record InputNote.Input velocity, similar to how a pitch track is edited and created.

• state_kbd_entry :: !Bool

  Use the alphanumeric keys to enter notes in addition to midi input.

• state_time_step :: !TimeStep.TimeStep

  Default time step for cursor movement.

• state_note_duration :: !TimeStep.TimeStep

  Used for note duration. It's separate from state_time_step to allow for tracker-style note entry where newly entered notes extend to the next note or the end of the block.

• state_note_orientation :: !Types.Orientation

  If this is Negative, create notes with negative durations.

• state_note_text :: !Text

  New notes get this text by default. This way, you can enter a series of notes with the same attributes, or whatever.

• state_kbd_entry_octave :: !Pitch.Octave

  Transpose note entry on the keyboard by this many octaves. It's by octave instead of scale degree since scales may have different numbers of notes per octave.

• state_recorded_actions :: !RecordedActions
   
• state_instrument_attributes :: !(Map ScoreT.Instrument Attrs.Attributes)
   
• state_edit_box :: !(Block.Box, Block.Box)

  See set_edit_box.

Fields

• hooks_selection :: [[(ViewId, Maybe.Maybe TrackSelection)] -> CmdId ()]

  Run when the selection changes.

Fields

• sync_device :: !Midi.WriteDevice
   
• sync_device_id :: !Mmc.DeviceId

  Send MMC to this device.

• sync_mtc :: !Bool

  If true, send MTC on the sync_device. If this is set, MMC play and stop will be omitted, since the presence of MTC should be enough to get the DAW started, provided it's in external sync mode.

  DAWs tend to spend a long time synchronizing, presumably because hardware devices take time to spin up. That's unnecessary in software, so in Cubase you can set "lock frames" to 2, and in Reaper you can set "synchronize by seeking ahead" to 67ms.

• sync_frame_rate :: !Midi.FrameRate
   

Fields

• step_view_id :: !ViewId

  Keep track of the view step play was started in, so I know where to display the selection.

• step_tracknums :: [Types.TrackNum]

  If step play only applies to a few tracks, list them. If null, step play applies to all tracks.

• step_before :: ![(ScoreTime, State)]

  MIDI states before the step play position, in descending order.

• step_after :: ![(ScoreTime, State)]

  MIDI states after the step play position, in asceding order.

Fields

• state_play_control :: ![Transport.PlayControl]

  Transport control channel for the player, if one is running. This is a list even though I only expect one to run at a time. The reason is that if starting a new one stops the old one, there will be a small window where the old one has not exited yet. It's probably better to wait for the previous one to exit, but I've also had bugs where play gets stuck on, that makes me think with the concurrency I'm going to wind up with overlapping anyway, so I may as well handle it when I see it.

• state_performance :: !(Map BlockId Performance)

  When changes are made to a block, its performance will be recalculated in the background. When the Performance is forced, it will replace the existing performance in state_performance, if any. This means there will be a window in which the performance is out of date, but this is better than hanging the responder every time it touches an insufficiently lazy part of the performance.

• state_current_performance :: !(Map BlockId Performance)

  However, some cmds, like play, want the most up to date performance even if they have to wait for it. This map will be updated immediately.

• state_performance_threads :: !(Map BlockId Thread)

  Keep track of current thread working on each performance. If a new performance is needed before the old one is complete, it can be killed off.

• state_play_step :: !TimeStep.TimeStep

  Some play commands start playing from a short distance before the cursor.

• state_step :: !(Maybe.Maybe StepState)

  Contain a StepState if step play is active. Managed in Cmd.StepPlay.

• state_play_multiplier :: RealTime.RealTime

  Globally speed up or slow down performance. It mutiplies the timestamps by the reciprocal of this amount, so 2 will play double speed, and 0.5 will play half speed.

• state_sync :: !(Maybe.Maybe SyncConfig)

  If set, synchronize with a DAW when the selection is set, and on play and stop.

• state_im_progress :: !(Map BlockId (Map TrackId (Map ScoreT.Instrument (RealTime.RealTime, RealTime.RealTime))))

  Track im progress as updated by Msg.ImRenderingRange. This is ultimately displayed on the GUI, but I keep track here so I can take minimum and maximum when multiple instruments live on one track.

• state_previous_play :: !(Maybe.Maybe PlayCmd)
   

Fields

• config_app_dir :: !Path.AppDir

  App root, initialized from get_app_dir.

• config_save_dir :: !Path.Canonical
   
• config_midi_interface :: !Interface.Interface
   
• config_ky_paths :: ![FilePath]

  Search path for local definition files, from definition_path.

• config_rdev_map :: !(Map Midi.ReadDevice Midi.ReadDevice)

  Reroute MIDI inputs and outputs. These come from rdev_map and wdev_map and probably shouldn't be changed at runtime.

• config_wdev_map :: !(Map Midi.WriteDevice Midi.WriteDevice)

  WriteDevices can be score-specific, though, so another map is kept in Ui.State, which may override the one here.

• config_instrument_db :: !InstrumentDb
   
• config_builtins :: !Builtins

  Library of calls for the deriver.

• config_highlight_colors :: !(Map Color.Highlight Color.Color)
   
• config_im :: !Shared.Config.Config
   
• config_im_play_direct :: Bool

  If True, play im audio directly instead of via the play_cache VST. This means you don't need a DAW, but if you have MIDI instruments they probably won't be very in sync.

• config_git_user :: !SaveGitT.User
   

Fields

• kc_mods :: Set Modifier
   
• kc_octave :: Pitch.Octave
   
• kc_is_kbd_entry :: Bool
   
• kc_track_type :: Maybe.Maybe ParseTitle.Type
   
• kc_instrument :: Maybe.Maybe ScoreT.Instrument
   
• kc_scale_id :: Maybe.Maybe Pitch.ScaleId
   

Fields

• _saved_state :: !SavedState
   
• _editor_open :: !Bool
   

Fields

• state_config :: !Config
   
• state_save_file :: !(Maybe.Maybe (Writable, SaveFile))

  If set, the current Ui.State was loaded from this file. This is so save can keep saving to the same file.

• state_saved :: !Saved
   
• state_ky_cache :: !(Maybe.Maybe KyCache)
   
• state_derive_immediately :: !(Set BlockId)

  Omit the usual derive delay for these blocks, and trigger a derive. This is set by integration, which modifies a block in response to another block being derived. Blocks set to derive immediately are also considered to have block damage, if they didn't already. This is cleared after every cmd.

• state_history :: !History

  History.

• state_history_config :: !HistoryConfig
   
• state_history_collect :: !HistoryCollect
   
• state_selection_history :: !SelectionHistory
   
• state_keys_down :: !(Map Modifier Modifier)

  Map of keys held down. Maintained by cmd_record_keys and accessed with keys_down. The key is the modifier stripped of extraneous info, like mousedown position. The value has complete info.

• state_focused_view :: !(Maybe.Maybe ViewId)

  The block and track that have focus. Commands that address a particular block or track will address these.

• state_screens :: ![Rect.Rect]

  This contains a Rect for each screen. The first one is the default one, if a default is needed, though normally views should show up next to other views.

• state_keycaps :: !(Maybe.Maybe KeycapsState)

  Just indicates that the keycaps window is open. The window is global, stored in Ui.PtrMap, so I don't need to store it here.

• state_keycaps_update :: !(Maybe.Maybe KeycapsUpdate)
   
• state_global_status :: !(Map Text Text)

  This is similar to view_status, except that it's global instead of per-view. So changes are logged with a special prefix so logview can catch them. Really I only need this map to suppress log spam.

• state_play :: !PlayState
   
• state_hooks :: !Hooks
   
• state_wdev_state :: !WriteDeviceState

  MIDI state of WriteDevices.

• state_rdev_state :: !InputNote.ReadDeviceState

  MIDI state of ReadDevices, including configuration like pitch bend range.

• state_edit :: !EditState
   
• state_repl_status :: !Status

  The status return for this Cmd. This is used only by the REPL, since non-REPL cmds simply return Status as their return value. REPL cmds can't do that because they commonly use the return value to return an interesting String back to the REPL.

• state_debug :: !Bool

  Enable various debug printing to stdout.

Fields

• play_score_path :: FilePath
   
• play_block_id :: BlockId
   
• play_muted :: Set ScoreT.Instrument
   
• play_start :: RealTime.RealTime
   

Fields

• play_sync :: !(Maybe.Maybe SyncConfig)
   
• play_name :: !Text

  Description of what is being played for logging.

• play_midi :: !Midi.Perform.MidiEvents
   
• play_sc :: !Sc.Note.PlayNotes
   
• play_inv_tempo :: !(Maybe.Maybe Transport.InverseTempoFunction)
   
• play_repeat_at :: !(Maybe.Maybe RealTime.RealTime)
   
• play_im_end :: !(Maybe.Maybe RealTime.RealTime)

  Since im playback is done by the VST, I don't directly control it as I do with the MIDI player, effectively all the sound is "in the decay." So I have an explicit end, and the MIDI thread will pretend it's still playing until it crosses this boundary.

• play_im_direct :: !(Maybe.Maybe PlayDirectArgs)
   

Fields

• cmd_name :: !Text
   
• cmd_call :: !(Msg.Msg -> m Status)
   

Fields

• perf_derive_cache :: Cache
   
• perf_events :: Vector Score.Event

  This is the forced result of a derivation.

• perf_logs :: [Log.Msg]

  Logs from the derivation are written separately.

• perf_logs_written :: Bool

  The logs are only written on the first play, to minimize error spam. So there's a flag which says whether these logs have been written or not. I don't clear the logs, so cache_stats can inspect them.

• perf_track_dynamic :: TrackDynamic
   
• perf_integrated :: [Integrated]
   
• perf_damage :: ScoreDamage

  ScoreDamage is normally calculated automatically from the UI diff, but Cmds can also intentionally inflict damage to cause a rederive.

• perf_warps :: [TrackWarp.TrackWarp]
   
• perf_track_signals :: TrackSignals
   
• perf_block_deps :: BlockDeps
   
• perf_track_instruments :: Map TrackId (Set ScoreT.Instrument)

  Map each track to the instruments on it. This tries to remain lazy, since it's only used by muted_im_instruments.

• perf_ui_state :: Ui.State

  This is the score state at the time of the performance. It's needed to interpret perf_track_signals, because at the time signals are sent (in cmd_play_msg), the Ui.State may have unsynced changes.