Laborejo/engine/api.py

#! /usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Copyright 2018, Nils Hilbricht, Germany ( https://www.hilbricht.net )

This file is part of the Laborejo Software Suite ( https://www.laborejo.org ),
more specifically its template base application.

The Template Base Application is free software: you can redistribute it and/or modify
it under the terms of the GNU 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 General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
"""

import logging; logging.info("import {}".format(__file__))

#Python Standard Library
import sys
import random

#Third Party Modules

#Template Modules
import template.engine.api #we need direct access to the module to inject data in the provided structures. but we also need the functions directly. next line:
from template.engine.api import *
from template.engine.duration import DB, DL, D1, D2, D4, D8, D16, D32, D64, D128, D256, D512, D1024, D_DEFAULT, D_STACCATO, D_TENUTO, D_TIE
import template.engine.pitch as pitchmath
from template.helper import flatList, EndlessGenerator

#Our Modules
from . import items
from . import lilypond
from .graphtracks import TempoItem
from .track import Track

apiModuleSelfReference = sys.modules[__name__]

#New callbacks
class ClientCallbacks(Callbacks): #inherits from the templates api callbacks
    def __init__(self):
        super().__init__()

        self.setCursor = []
        self.setSelection = []

        self.tracksChanged = []
        self.tracksChangedIncludingHidden = []
        self.updateTrack = []
        self.updateBlockTrack = []
        
        #self.playbackStart = []
        #self.playbackStop = []
        self.playbackSpeedChanged = []
        self._cachedTickIndex = -1

        self.updateGraphTrackCC = []
        self.graphCCTracksChanged = []
        self.updateGraphBlockTrack = []

        self.updateTempoTrack = []
        self.updateTempoTrackBlocks = []
        self.updateTempoTrackMeta = []

        self.prevailingBaseDurationChanged = []        
        self.metronomeChanged = []

        #self.recordingStreamNoteOn = []
        #self.recordingStreamNoteOff = []
        #self.recordingStreamClear = []

    def _dataChanged(self):
        """Only called from within the callbacks.
        This is about data the user cares about. In other words this is the indicator if you need
        to save again.

        The data changed when notes are inserted, track names are changed, a CC value is added etc.
        but not when the cursor moves, the metronome is generated or the playback tick advances.
        """
        session.nsmClient.announceSaveStatus(False)
        self._historyChanged()

    def _setCursor(self, destroySelection = True):
        """set a new cursor position.
        Only do destroySelection = False if you really modify the
        selection. If in doubt: destroy it. """
        if destroySelection or session.history.doNotRegisterRightNow or session.history.duringRedo:
            session.data.cursorWhenSelectionStarted = None

        if self.setCursor:
            ex = session.data.cursorExport()
            for func in self.setCursor:
                func(ex)

        """Exports a tuple of cursors. This is to indicate a GUI to
        draw a selection rectangle or so. Not for processing. Because:
        The exported top left item is included in the selection.
        The exported bottom right item is NOT in the selection.
        But for a GUI it looks like the rectangle goes to the current
        cursor position, which appears to be left of the current item."""
        ex = session.data.selectionExport()
        for func in self.setSelection:
            func(ex)

    def _updateChangedTracks(self):
        """Determines which tracks have changed in the step before
        this callback and calls an update for those"""
        changedTracks, currentItem = session.data.currentContentLinkAndItsBlocksInAllTracks()
        for track in changedTracks:
            self._updateTrack(id(track))

    def  _updateTrack(self, trId):
        """The most important function. Create a static representation of the music data which
        can be used by a GUI to draw notes.
        track.staticRepresentation also creates the internal midi representation for cbox. """
        if self.updateTrack:
            ex = session.data.trackById(trId).staticRepresentation()
            for func in self.updateTrack:
                func(trId, ex)
            self._updateBlockTrack(trId)

    def _updateBlockTrack(self, trId):
        if self.updateBlockTrack:
            ex = session.data.trackById(trId).staticBlocksRepresentation()
            for func in self.updateBlockTrack:
                func(trId, ex)
        
        self._updateTempoTrack() #The last Tempo Block reacts to changing score sizes.
        self._dataChanged()

    def _updateGraphTrackCC(self, trId, cc):
        """No cursor, so it always needs a graphTrack Id.
        Also handles a GraphBlock overview callback,
        for extra block view or background colors."""

        #For simplistic reasons we just update all of this CC in all tracks.
        #Makes things much simple with content links across tracks.
        #We will see how that turns out performance wise.

        #We keep the trId parameter but don't use it.

        for track in session.data.tracks:
            if cc in track.ccGraphTracks:
                graphTrackCC = track.ccGraphTracks[cc]
                trId = id(track)
                ex = graphTrackCC.staticRepresentation()
                for func in self.updateGraphTrackCC:
                    func(trId, cc, ex)

                ex = graphTrackCC.staticGraphBlocksRepresentation()
                for func in self.updateGraphBlockTrack:
                    func(trId, cc, ex)

    def _updateSingleTrackAllCC(self, trId):
        """Used on CC-Channels change. No own callback list."""
        for cc, graphTrackCC in session.data.trackById(trId).ccGraphTracks.items():
            ex = graphTrackCC.staticRepresentation()
            for func in self.updateGraphTrackCC:
                func(trId, cc, ex)


    def _graphCCTracksChanged(self, trId):
        """CC graphs of a track deleted or added"""
        #TODO: moved?
        if self.graphCCTracksChanged:            
            ex = list(session.data.trackById(trId).ccGraphTracks.keys())  # list of ints from 0 to 127
            for func in self.graphCCTracksChanged:
                func(trId, ex)
        self._dataChanged()

    def _tracksChanged(self):
        """Track deleted, added or moved. Or toggled double/non-double.
        This callback is relatively cheap because it does not generate
        any item data."""                
        session.data.updateJackMetadataSorting()
        
        if self.tracksChanged:
            ex = session.data.listOfStaticTrackRepresentations()
            for func in self.tracksChanged:
                func(ex)

        if self.tracksChangedIncludingHidden:
            exHidden  = session.data.listOfStaticHiddenTrackRepresentations()
            for func in reversed(self.tracksChangedIncludingHidden):
                func(ex + exHidden)
        self._dataChanged()
        self._metronomeChanged() #because the track name is sent here.

    def _updateTempoTrack(self):
        """Sends the block update as well.
        staticRepresentations also updates midi.
        
        Of course the order is: track meta, then blocks first, then items.
        This must not change! The GUI depends on it."""
                
        if self.updateTempoTrackMeta:
            ex = session.data.tempoTrack.staticTrackRepresentation() #only track metadata, no block information. parses all items.
            for func in self.updateTempoTrackMeta:
                func(ex)

        if self.updateTempoTrackBlocks:
            ex = session.data.tempoTrack.staticGraphBlocksRepresentation() #block boundaries and meta data. Does not parse items therefore cheap to call.
            for func in self.updateTempoTrackBlocks:
                func(ex)

        if self.updateTempoTrack:
            ex = session.data.tempoTrack.staticRepresentation() #export all items. performance-expensive.
            for func in self.updateTempoTrack:
                func(ex)

        #TODO: We need blocks before items, but also blocks after items. This is a cheap call though.
        if self.updateTempoTrackBlocks:
            ex = session.data.tempoTrack.staticGraphBlocksRepresentation() #yes, we need to regenerate that. That is the problem. #TODO.
            for func in self.updateTempoTrackBlocks:
                func(ex)

        self._dataChanged()
        #since the exported cursor also has a tempo entry it needs updating as well
        #TODO: but this also leads to centerOn cursor in the gui after every mouse click in the conductor.
        #self._setCursor(destroySelection = False)

    def _playbackStart(self):
        for func in self.playbackStart:
            func()

    def _playbackStop(self):
        for func in self.playbackStop:
            func()

    def _playbackSpeedChanged(self, newValue):
        for func in self.playbackSpeedChanged:
            func(newValue)

    def _prevailingBaseDurationChanged(self, newPrevailingBaseDuration):
        for func in self.prevailingBaseDurationChanged:
            func(newPrevailingBaseDuration)

    def _historyChanged(self):
        """sends two lists of strings.
        the first is the undoHistory, the last added item is [-1]. We can show that to a user to
        indicate what the next undo will do.

        the second is redoHistory, same as undo: [-1] shows the next redo action."""
        undoHistory, redoHistory = session.history.asList()
        for func in self.historyChanged:
            func(undoHistory, redoHistory)

    def _metronomeChanged(self):
        """returns a dictionary with meta data such as the mute-state and the track name"""
        #Check if the actual track exists. This handles track delete of any kind.
        #session.data.metronome.currentMetronomeTrack is not a calf box track but our Laborejo track that HOLDS the current cbox metronome track
        return #TODO
        if not session.data.metronome.currentMetronomeTrack or  not (session.data.metronome.currentMetronomeTrack in session.data.tracks or session.data.metronome.currentMetronomeTrack in session.data.hiddenTracks):
            session.data.metronome.currentMetronomeTrack = None
            session.data.metronome.useTrack(session.data.currentTrack())

        for func in self.metronomeChanged:
            func(session.data.metronome.staticRepresentation())

    def _recordingStreamNoteOn(self, liveChord):
        """One dict at a time"""
        trId = id(session.data.currentTrack())
        for func in self.recordingStreamNoteOn:
            func(trId, liveChord)

    def _recordingStreamNoteOff(self, liveChord):
        """One dict at a time"""
        trId = id(session.data.currentTrack())
        for func in self.recordingStreamNoteOff:
            func(trId, liveChord)

    def _recordingStreamClear(self):
        for func in self.recordingStreamClear:
            func()

#Inject our derived Callbacks into the parent module
template.engine.api.callbacks = ClientCallbacks()
from template.engine.api import callbacks


_templateStartEngine = startEngine
def startEngine(nsmClient):
    _templateStartEngine(nsmClient)
    
    #Send initial Data etc.    
    session.data.tempoMap.isTransportMaster = True #always true for Laborejo.
    callbacks._tracksChanged()  # This creates the frontend/GUI tracks with access through track ids. From now on we can send the GUI a trId and it knows which track needs change.
    for trId in session.data.listOfTrackIds():
        callbacks._updateTrack(trId) #create content: music items
        callbacks._updateTempoTrack() # does everything at once
        callbacks._graphCCTracksChanged(trId) #create structure: all CC graphs, accessed by CC number (0-127)
        for cc in session.data.trackById(trId).listOfCCsInThisTrack():
            callbacks._updateGraphTrackCC(trId, cc) #create content: CC points. user points and interpolated points.

    for track in session.data.hiddenTracks: #After loading a file some tracks could be hidden. We want midi for them as well.
        track.staticRepresentation()  #that generates the calfbox data as a side effect. discard the other data.

    callbacks._setCursor()       
    
    global laborejoEngineStarted #makes for a convenient check. stepMidiInput uses it, which needs to know that the gui already started the api.
    laborejoEngineStarted = True
    
#General and abstract Commands

def playFromCursor():
    playFrom(ticks=session.data.cursorExport()["tickindex"])    

topLevelFunction = None
def simpleCommand(function, autoStepLeft = True, forceReturnToItem = None):
    """
    simpleCommand demands that the cursor is on the item you want to
    change. That means for scripting and working with selections
    that you can't simply iterate over block.data, which is a list.
    Well you can, but then you don't get the context data which is in
    track.state.

    Recursive commands are not allowed"""
    global topLevelFunction  #todo: replace with a python-context
    if not topLevelFunction:
         topLevelFunction = function

    if autoStepLeft and session.data.currentTrack().state.isAppending():
        session.data.currentTrack().left()
        function() #<-------- The action
        session.data.currentTrack().right()
    else:
        function() #<-------- The action

    if forceReturnToItem:
        curBlock, curItem = forceReturnToItem
        session.data.currentTrack().toItemInBlock(curItem, curBlock) #even works with appending positions (None)

    if function == topLevelFunction:
        callbacks._updateChangedTracks() #works with the current item @ cursor.
        callbacks._setCursor()
        topLevelFunction = None

def insertItem(item):
    orderBeforeInsert = session.data.getBlockAndItemOrder()
    moveFunction = _createLambdaMoveToForCurrentPosition()    
    if session.data.currentTrack().insert(item):        
        def registeredUndoFunction():            
            moveFunction()
            _changeBlockAndItemOrder(orderBeforeInsert)
        session.history.register(registeredUndoFunction, descriptionString=f"Insert {item}")        
        simpleCommand(nothing, autoStepLeft = False) #for callbacks        
        callbacks._historyChanged()

def insertItemAtTickindex(item, tickindex):
    #session.data.currentTrack().goToTickindex

    """
    Das ist eine conversion in der session. keine api befehle benutzen.
    hier weiter machen. Der Cursor muss in Ruhe gelassen werden. Oder aber ich resette ohne callback? das erscheint mir erstmal simpler.
    Ich brauch aber eine Funktion goToTickindex im Track die Pausen erstellt wenn man da nicht hinkommt.  Jetzt wünsch ich mir ich hätte die Noten nicht in ner liste sondern in einem dict mit tickindex. welp...
    vielleicht brauch ich eine komplette parallelwelt. das midi modul sollte auf jeden fall nicht die keysig suchen müssen. kontext wird in der api hergestellt, nicht im midi
    """

def _createLambdaMoveToForCurrentPosition():
    """for undo only"""
    def moveTo(trackIndex, blockIndex, localCursorIndexInBlock, pitchindex):
        try:
            session.data.goTo(trackIndex, blockIndex, localCursorIndexInBlock)
            session.data.cursor.pitchindex = pitchindex
        except: #the worst that can happen is wrong movement.
            pass
    trackIndex, blockIndex, localCursorIndexInBlock = session.data.where()
    moveFunction = lambda trIdx=trackIndex, blIdx=blockIndex, curIdx=localCursorIndexInBlock, pitchIdx=session.data.cursor.pitchindex: moveTo(trIdx, blIdx, curIdx, pitchIdx)
    return moveFunction

#The following function is not neccesary. A selection is a user-created thing, not something you need for internal processing, especially not for undo.
#Leave it as reminder.
#def _createLambdaRecreateSelection():
#    """for undo only
#    Call it when you still have a selection, right after you do the
#    processing you want to undo.
#
#    A valid selection implies that the cursor is on one end
#    of the selection. It doesn't matter which one but for the
#    sake of consistency and convenience we make sure that we end up with
#    the cursor on the bottomRight position.
#    It is entirely possible that the selection changed
#    the duration and the dimensions. The bottom right item might not
#    be on the same tickindex nor does it need to exist anymore.
#    Only the topLeft position is guaranteed to exist and have the same
#    tickindex. The item on that position however may not be there
#    anymore.
#    """
#    def recreateSelection(moveToFunction, topLeftCursor, bottomRightCursor):
#        session.data.cursorWhenSelectionStarted = None #take care of the current selection
#        moveToFunction()
#        session.data.goTo(topLeftCursor["trackIndex"], topLeftCursor["blockindex"], topLeftCursor["localCursorIndex"])
#        session.data.setSelectionBeginning()
#        session.data.goTo(bottomRightCursor["trackIndex"], bottomRightCursor["blockindex"], bottomRightCursor["localCursorIndex"])
#
#    assert session.data.cursorWhenSelectionStarted #only call this when you still have a selection
#    createSelectionFunction = lambda moveTo=_createLambdaMoveToForCurrentPosition(), tL=session.data.cursor.exportObject(session.data.currentTrack().state), bR=session.data.cursorWhenSelectionStarted, : recreateSelection(moveTo, tL, bR)
#    return createSelectionFunction #When this function gets called we are back in the position that the newly generated data is selected, ready to to the complementary processing.


def _updateCallbackForListOfTrackIDs(listOfChangedTrackIds):
    for trackId in listOfChangedTrackIds:
        callbacks._updateTrack(trackId)

def _updateCallbackAllTracks():
    _updateCallbackForListOfTrackIDs(session.data.listOfTrackIds())

updateCallbackAllTracks = _updateCallbackAllTracks

def useCurrentTrackAsMetronome():
    track = session.data.currentTrack()
    session.data.metronome.useTrack(track)
    callbacks._metronomeChanged() #updates playback as well

def enableMetronome(value):
    session.data.metronome.enabled = value #has side effects
    callbacks._metronomeChanged() #updates playback as well

def isMetronomeEnabled():
    return session.data.metronome.enabled

def toggleMetronome():
    enableMetronome(not session.data.metronome.enabled) #handles callback etc.

def _changeBlockAndItemOrder(dictWithTrackIDsAndDataLists):
    """A helper function for deleteSelection, paste and other...
    This makes it possible to undo/redo properly. It registers
    itself with complementary data as undo/redo."""    
    orderBeforeInsert = session.data.getBlockAndItemOrder() #save the current version as old version. as long as we keep this data around, e.g. in the undo stack, the items will not be truly deleted 
    moveFunction = _createLambdaMoveToForCurrentPosition() #the goTo function for the cursor is not exactly in the right place. It may end up on the "other" side of a selection. Which is close enough.
    def registeredUndoFunction():            
        moveFunction()
        _changeBlockAndItemOrder(orderBeforeInsert)
    session.history.register(registeredUndoFunction, descriptionString="change order")        

    #Replace old data with new parameter-data.
    listOfTrackIDs = session.data.putBlockAndItemOrder(dictWithTrackIDsAndDataLists)

    #Make changes visible in the GUI
    _updateCallbackForListOfTrackIDs(listOfTrackIDs)
    callbacks._setCursor()

def cutObjects():
    copyObjects()
    _deleteSelection()

def _deleteSelection(backspaceParamForCompatibilityIgnoreThis = None): #this is so special it gets its own command and is not part of the single delete() command.
    orderBeforeDelete = session.data.getBlockAndItemOrder()
    moveFunction = _createLambdaMoveToForCurrentPosition() 
    
    listOfChangedTrackIDs = session.data.deleteSelection()
    if listOfChangedTrackIDs: #delete succeeded.       
        def registeredUndoFunction():            
            moveFunction()
            _changeBlockAndItemOrder(orderBeforeDelete)
        session.history.register(registeredUndoFunction, descriptionString="delete selection")        

        #Make changes visible in the GUI and midi
        for trackId in listOfChangedTrackIDs:
            callbacks._updateTrack(trackId)
        callbacks._setCursor()

def copyObjects(): #ctrl+c
    session.data.copyObjects()
    #The score doesn't change at all. No callback.
    #no undo.

def pasteObjects(customBuffer = None, keepCursorState = False, overwriteSelection = True): #ctrl+v
    """api.duplicate overrides default paste behaviour by providing its own copyBuffer
    and not destroying the selection/keep the cursor at its origin position
    """
    dataBefore = session.data.getBlockAndItemOrder()
    moveFunction = _createLambdaMoveToForCurrentPosition()
    listOfChangedTrackIDs = session.data.pasteObjects(customBuffer, overwriteSelection)
    if listOfChangedTrackIDs: #paste succeeded.
        def registeredUndoFunction():            
            moveFunction()
            _changeBlockAndItemOrder(dataBefore)
        session.history.register(registeredUndoFunction, descriptionString="paste")             

        #Make changes visible in the GUI
        for trackId in listOfChangedTrackIDs:
            callbacks._updateTrack(trackId)

        if keepCursorState:
            goTo()
            callbacks._setCursor(destroySelection = False)
        else:
            callbacks._setCursor()

def duplicate(): #ctrl+d
    """Duplicate a single object and put it right of the original. Duplicate the entire selection
    and put the copy right of the last selected note.
    Basically a special case of copy and paste that does not touch the clipboard."""
    if session.data.cursorWhenSelectionStarted:
        #startPos = session.data.where() #we cannot use where() since we don't know if a content linked block before our current position gets new items in the duplication process
        #TODO: when duplicating with content links or at least inside a content link the selection gets lost completely. Maybe this cannot be avoided, but review that in the future.

        customBuffer = session.data.copyObjects(writeInSessionBuffer = False)
        if customBuffer:
            session.data.goToSelectionStart()
            pasteObjects(customBuffer = customBuffer, keepCursorState = True, overwriteSelection = False)
    else:
        item = session.data.currentItem()
        if item:
            insertItem(item.copy())
           
            
#Score
def transposeScore(rootPitch, targetPitch):
    """Based on automatic transpose. The interval is caculated from two pitches.
    There is also tranpose. But no transposeTrack, this is just select track and transpose."""
    session.data.transposeScore(rootPitch, targetPitch)    
    session.history.register(lambda r=rootPitch,t=targetPitch: transposeScore(t,r), descriptionString="transpose score")    
    _updateCallbackAllTracks()

#Tracks
def insertTrack(atIndex, trackObject):
    moveFunction = _createLambdaMoveToForCurrentPosition()
    newTrackId = id(trackObject)
    session.data.insertTrack(atIndex, trackObject) #side-effect: changes the active track to the new track which can be used in the next step:
    def registeredUndoFunction():            
        moveFunction()
        deleteTrack(newTrackId)
    session.history.register(registeredUndoFunction, descriptionString = "insert track")
    callbacks._tracksChanged()
    callbacks._updateTrack(newTrackId)
    callbacks._setCursor()

def newEmptyTrack():
    """Append an empty track and switch to the new track"""
    newIndex = len(session.data.tracks)
    newTrack = Track(session.data)
    insertTrack(newIndex, newTrack) #handles callbacks and undo
    return (id(newTrack))

def deleteTrack(trId):
    """Can not delete hidden tracks because these don't implement undo.
    A hidden track is already considered "deleted" by the program.
    Therefore you can only delete visible tracks."""
    trackObject = session.data.trackById(trId)
    assert trackObject not in session.data.hiddenTracks #enforce docstring.
    trackIndex = session.data.tracks.index(trackObject)
    didDelete = session.data.deleteTrack(trackObject) #may or may not change the trackindex. In any case, logically the cursor is now in a different track.
    if didDelete: #score.deleteTrack does not delete the last remaining track
        def registeredUndoFunction():            
            trackObject.sequencerInterface.recreateThroughUndo()
            insertTrack(trackIndex, trackObject)        
        session.history.register(registeredUndoFunction, descriptionString = "delete track")
        callbacks._tracksChanged()
        callbacks._setCursor()
        callbacks._metronomeChanged()

def deleteCurrentTrack():
    deleteTrack(id(session.data.currentTrack()))

def hideTrack(trId):
    """For the callbacks this looks like a delete. But there is no undo.
    The track still emits playback.

    hide and unhide track register in the history. deleteItem depends on the item to be in a visible
    track so it may possible to insert an item, hide the track and then undo which would try to
    delete an item in a hidden track. Therefore hide and unhide register.
     """
    trackObject = session.data.trackById(trId)
    result = session.data.hideTrack(trackObject)
    if result: #not the only track
        session.history.register(lambda trId=trId: unhideTrack(trId), descriptionString = "hide track")
    callbacks._tracksChanged() #even if there is no change the GUI needs to be notified to redraw its checkboxes that may have been enabled GUI-side.
    callbacks._setCursor()

def unhideTrack(trId):
    trackObject = session.data.trackById(trId)
    session.data.unhideTrack(trackObject) #always succeeds, or throws error.
    session.history.register(lambda trId=trId: hideTrack(trId), descriptionString = "unhide track")
    callbacks._tracksChanged()
    callbacks._updateTrack(trId)
    #the cursor is uneffected

def listOfTrackIds():
    return session.data.listOfTrackIds()

def listOfHiddenTrackIds():
    return [id(track) for track in session.data.hiddenTracks.keys()]

def rearrangeTracks(listOfTrackIds):
    if len(session.data.tracks) <= 1:
        return
    session.history.register(lambda l=session.data.asListOfTrackIds(): rearrangeTracks(l), descriptionString = "rearrange tracks")
    session.data.rearrangeTracks(listOfTrackIds)
    callbacks._tracksChanged()
    callbacks._setCursor()

def setTrackName(trId, nameString, initialInstrumentName, initialShortInstrumentName):
    trackObject = session.data.trackById(trId)
    session.history.register(lambda i=trId, n=trackObject.name, lyN=trackObject.initialInstrumentName, lySN=trackObject.initialShortInstrumentName: setTrackName(i, n, lyN, lySN), descriptionString = "change track name")
    trackObject.name = nameString # this is a setter. It changes calfbox as well.
    trackObject.initialInstrumentName = initialInstrumentName
    trackObject.initialShortInstrumentName = initialShortInstrumentName
    callbacks._tracksChanged()

def setTrackUpbeat(trId, upbeatInTicks):
    trackObject = session.data.trackById(trId)
    session.history.register(lambda i=trId, u=trackObject.upbeatInTicks: setTrackUpbeat(i, u), descriptionString = "change track upbeat")
    trackObject.upbeatInTicks = upbeatInTicks
    callbacks._updateTrack(trId)

def setDoubleTrack(trId, statusBool):
    """It does not touch any important data because it is more or less
    a savefile-persistent visual convenience feature.
    So we don't need undo/redo"""
    trackObject = session.data.trackById(trId)
    trackObject.double = statusBool
    callbacks._tracksChanged()
    callbacks._updateTrack(trId)
    callbacks._setCursor()

def setTrackSettings(trId, dictionary):
    """We need to create a new playback of the track to update the midi data."""
    trackObject = session.data.trackById(trId)
    previousSettings = trackObject.staticTrackRepresentation()
    clean = True

    for key, value in dictionary.items():
        #this assumes keys are the same as track export. Will give a key error at least if not.
        if not previousSettings[key] == value:
            clean = False
            break

    if not clean:
        trackObject.initialMidiChannel = dictionary["initialMidiChannel"]
        trackObject.initialMidiBankMsb = dictionary["initialMidiBankMsb"]
        trackObject.initialMidiBankLsb = dictionary["initialMidiBankLsb"]
        trackObject.initialMidiProgram = dictionary["initialMidiProgram"]
        trackObject.ccChannels = dictionary["ccChannels"]
        trackObject.midiTranspose = dictionary["midiTranspose"]
        trackObject.durationSettingsSignature.defaultOn = dictionary["duration.defaultOn"]
        trackObject.durationSettingsSignature.defaultOff = dictionary["duration.defaultOff"]
        trackObject.durationSettingsSignature.staccatoOn = dictionary["duration.staccatoOn"]
        trackObject.durationSettingsSignature.staccatoOff = dictionary["duration.staccatoOff"]
        trackObject.durationSettingsSignature.tenutoOn = dictionary["duration.tenutoOn"]
        trackObject.durationSettingsSignature.tenutoOff = dictionary["duration.tenutoOff"]
        trackObject.durationSettingsSignature.legatoOn = dictionary["duration.legatoOn"]
        trackObject.durationSettingsSignature.legatoOff = dictionary["duration.legatoOff"]

        trackObject.dynamicSettingsSignature.dynamics["ppppp"] = dictionary["dynamics.ppppp"]
        trackObject.dynamicSettingsSignature.dynamics["pppp"] = dictionary["dynamics.pppp"]
        trackObject.dynamicSettingsSignature.dynamics["ppp"] = dictionary["dynamics.ppp"]
        trackObject.dynamicSettingsSignature.dynamics["pp"] = dictionary["dynamics.pp"]
        trackObject.dynamicSettingsSignature.dynamics["p"] = dictionary["dynamics.p"]
        trackObject.dynamicSettingsSignature.dynamics["mp"] = dictionary["dynamics.mp"]
        trackObject.dynamicSettingsSignature.dynamics["mf"] = dictionary["dynamics.mf"]
        trackObject.dynamicSettingsSignature.dynamics["f"] = dictionary["dynamics.f"]
        trackObject.dynamicSettingsSignature.dynamics["ff"] = dictionary["dynamics.ff"]
        trackObject.dynamicSettingsSignature.dynamics["fff"] = dictionary["dynamics.fff"]
        trackObject.dynamicSettingsSignature.dynamics["ffff"] = dictionary["dynamics.ffff"]
        trackObject.dynamicSettingsSignature.dynamics["custom"] = dictionary["dynamics.custom"]
        trackObject.dynamicSettingsSignature.dynamics["tacet"] = dictionary["dynamics.tacet"]
        trackObject.dynamicSettingsSignature.dynamics["fp"] = dictionary["dynamics.fp"]
        trackObject.dynamicSettingsSignature.dynamics["sp"] = dictionary["dynamics.sp"]
        trackObject.dynamicSettingsSignature.dynamics["spp"] = dictionary["dynamics.spp"]
        trackObject.dynamicSettingsSignature.dynamics["sfz"] = dictionary["dynamics.sfz"]
        trackObject.dynamicSettingsSignature.dynamics["sf"] = dictionary["dynamics.sf"]
        trackObject.dynamicSettingsSignature.dynamics["sff"] = dictionary["dynamics.sff"]

        session.history.register(lambda trId=trId, previousSettings=previousSettings: setTrackSettings(trId, previousSettings), descriptionString = "change track settings")
        callbacks._tracksChanged()
        callbacks._updateSingleTrackAllCC(trId)
        callbacks._updateTrack(trId)

def resetDynamicSettingsSignature(trId):
    trackObject = session.data.trackById(trId)
    previousSettings = trackObject.staticTrackRepresentation()
    trackObject.dynamicSettingsSignature.reset()
    session.history.register(lambda trId=trId, previousSettings=previousSettings: setTrackSettings(trId, previousSettings), descriptionString = "reset track dynamic settings")
    callbacks._tracksChanged()
    #We only need this for midi changes. callbacks._updateSingleTrackAllCC(trId)
    callbacks._updateTrack(trId)

def resetDuationSettingsSignature(trId):
    trackObject = session.data.trackById(trId)
    previousSettings = trackObject.staticTrackRepresentation()
    trackObject.durationSettingsSignature.reset()
    session.history.register(lambda trId=trId, previousSettings=previousSettings: setTrackSettings(trId, previousSettings), descriptionString = "reset track duration settings")
    callbacks._tracksChanged()
    #We only need this for midi changes. callbacks._updateSingleTrackAllCC(trId)
    callbacks._updateTrack(trId)

#Blocks
def appendBlock(trackid = None):
    """
    Has dynamic behaviour:
        If we are at the end of track appending a Block switches into
        that new block.
        On any other position it just appends a block and the cursor
        stays where it is. This gives a better typing from left-to-right
        experience."""
    if trackid:
        tr = session.data.trackById(trackid)
    else:
        tr = session.data.currentTrack()
    block = tr.appendBlock()
    if tr.state.isAppending() and len(tr.blocks)-2 == tr.state.blockindex: #end of track?
        moveFunction = _createLambdaMoveToForCurrentPosition()
        def registeredUndoFunction():            
            moveFunction()
            deleteBlock(id(block))
        session.history.register(registeredUndoFunction, descriptionString = "append block")
        session.data.currentTrack().right()
    else:
        session.history.register(lambda blId = id(block): deleteBlock(blId), descriptionString = "append block")
    callbacks._updateTrack(id(tr))
    callbacks._setCursor()

def splitBlock():
    tr = session.data.currentTrack()
    if tr.state.isAppending() and len(tr.blocks)-1 == tr.state.blockindex: #end of track? Yes len-1 here and len-2 in append() is correct. I don't know why :(
        appendBlock()
    else: #a real split
        dictOfTrackIdsWithListOfBlockIds = session.data.splitCurrentBlockAndAllContentLinks() #do the split. We get the current state as return value for undo
        if dictOfTrackIdsWithListOfBlockIds:
            rearrangeBlocksInMultipleTracks(dictOfTrackIdsWithListOfBlockIds)  #handles undo and callbacks for redrawing
        callbacks._setCursor() #cursor is still on the same item. But the item might be further to the right now when additional block boundaries have been introduced to the left through contentLinks

def joinBlockWithNext(blockId):
    """written for the GUI which can join blocks with the mouse"""
    track, block = session.data.blockById(blockId)
    session.data.goTo(session.data.tracks.index(track), track.blocks.index(block), 0)
    joinBlock()

def joinBlock():
    """Opposite of splitBlock (but not undo)
    Take the current block and join it with the one after it.
    Does the same automatically for all content linked blocks.
    If there is no next block this will do nothing.

    It only works on content linked blocks if ALL content linked blocks have a different
    content linked block after them. So a block A needs always to be followed by block B.
    Joining those will result in one big new content linked block in the whole track.
    It is exactly the same as splitting a content linked block which will result in two new
    content links."""
    where = session.data.where() #just for the user experience.

    dictOfTrackIdsWithListOfBlockIds = session.data.joinCurrentBlockAndAllContentLinks()
    if dictOfTrackIdsWithListOfBlockIds:
        rearrangeBlocksInMultipleTracks(dictOfTrackIdsWithListOfBlockIds)  #handles undo and callbacks for redrawing

    session.data.goTo(*where) #just for the user experience.
    callbacks._setCursor()

def deleteBlock(blockId):
    track, block = session.data.blockById(blockId)
    oldBlockArrangement = track.asListOfBlockIds()
    parentTrack, deletedBlock = track.deleteBlock(block)
    if (parentTrack and deletedBlock): #not the last block
        #Blocks are never truly deleted but a stored in the Block.allBlocks dict. This keeps the reference to this deleted block alive and it can be added through rearrange, which gets its blocks from this dict.
        session.history.register(lambda i=id(track), l=oldBlockArrangement: rearrangeBlocks(i, l), descriptionString = "delete block")
        callbacks._updateTrack(id(track))
        callbacks._setCursor()

def deleteCurrentBlock():
    currentBlockId = id(session.data.currentTrack().currentBlock())
    deleteBlock(currentBlockId) #handles callbacks and undo

def deleteEmptyBlocks():
    """whole score"""
    dictOfTrackIdsWithListOfBlockIds = session.data.removeEmptyBlocks()
    if dictOfTrackIdsWithListOfBlockIds and all(l for l in dictOfTrackIdsWithListOfBlockIds.values()):
        rearrangeBlocksInMultipleTracks(dictOfTrackIdsWithListOfBlockIds)  #handles undo and callbacks for redrawing
    callbacks._setCursor()

def duplicateCurrentBlock():
    currentBlockId = id(session.data.currentTrack().currentBlock())
    duplicateBlock(currentBlockId, 1) #handles callbacks and undo

def duplicateContentLinkCurrentBlock():
    currentBlockId = id(session.data.currentTrack().currentBlock())
    duplicateContentLinkBlock(currentBlockId, 1) #handles callbacks and undo

def duplicateBlock(blockId, times = 1):
    track, block = session.data.blockById(blockId)
    session.history.register(lambda i=id(track), l=track.asListOfBlockIds(): rearrangeBlocks(i, l), descriptionString = "duplicate block")
    for i in range(times):
        track.duplicateBlock(block)
    callbacks._updateTrack(id(track))
    callbacks._setCursor()

def duplicateContentLinkBlock(blockId, times = 1):
    track, block = session.data.blockById(blockId)
    session.history.register(lambda i=id(track), l=track.asListOfBlockIds(): rearrangeBlocks(i, l), descriptionString = "content link block")
    for i in range(times):
        track.duplicateContentLinkBlock(block)
    callbacks._updateTrack(id(track))
    callbacks._setCursor()

def moveBlockToOtherTrack(blockId, newTrackId, listOfBlockIdsForNewTrack):
    """First move the block to the new track and then
    rearrange both tracks

    It is by design only possible that a block will be copied/linked
    in the same track, next to the original block.
    If you want the dual action of "copy this block to a new track" you need to do it in two steps.
    First copy.  It can be moved later by this api function."""
    oldTrack, block = session.data.blockById(blockId)
    assert oldTrack
    assert block

    if len(oldTrack.blocks) == 1:
        return False #it is not possible to move the last block.

    session.history.register(lambda blId=blockId, trId=id(oldTrack), l=oldTrack.asListOfBlockIds(): moveBlockToOtherTrack(blId, trId, l), descriptionString = "move block to other track")
    newTrack = session.data.trackById(newTrackId)
    newTrack.appendExistingBlock(block)
    newTrack.rearrangeBlocks(listOfBlockIdsForNewTrack)
    #We don't need to check if deleting succeeded because we already checked if there are more than 1 blocks in the track above.
    oldTrack.deleteBlock(block) #It is important that we delete the block at exactly this point in time, not ealier. Otherwise the reference for undo will go away.
    block.parentTrack = newTrack

    callbacks._updateTrack(id(oldTrack))
    callbacks._updateTrack(newTrackId)
    callbacks._setCursor()

def rearrangeBlocks(trackid, listOfBlockIds):
    track = session.data.trackById(trackid)
    oldBlockOrder = track.asListOfBlockIds()
    track.rearrangeBlocks(listOfBlockIds)
    
    moveFunction = _createLambdaMoveToForCurrentPosition()
    def registeredUndoFunction():            
        moveFunction()
        rearrangeBlocks(trackid, oldBlockOrder)    
    session.history.register(registeredUndoFunction, descriptionString = "rearrange blocks")
    callbacks._updateTrack(trackid)

def rearrangeBlocksInMultipleTracks(dictOfTrackIdsWithListOfBlockIds):
    """dictOfTrackIdsWithListOfBlockIds is [trackId] = [listOfBlockIds]"""
    forUndo = {}
    for trackId, listOfBlockIds in dictOfTrackIdsWithListOfBlockIds.items():
        track = session.data.trackById(trackId)
        oldBlockOrder = track.asListOfBlockIds()
        track.rearrangeBlocks(listOfBlockIds)
        forUndo[trackId] = oldBlockOrder

    moveFunction = _createLambdaMoveToForCurrentPosition()
    def registeredUndoFunction():            
        moveFunction()
        rearrangeBlocksInMultipleTracks(forUndo)
    session.history.register(registeredUndoFunction, descriptionString = "multi-track rearrange block")

    for trackId in dictOfTrackIdsWithListOfBlockIds.keys():
        callbacks._updateTrack(trackId)
    callbacks._setCursor()

def changeBlock(blockId, newParametersDict):
    """for example "name" or "minimumInTicks"  """
    track, block = session.data.blockById(blockId)
    moveFunction = _createLambdaMoveToForCurrentPosition()
    def registeredUndoFunction():            
        moveFunction()
        changeBlock(blockId, block.getDataAsDict())        
    session.history.register(registeredUndoFunction, descriptionString = "change block")
    block.putDataFromDict(newParametersDict)
    callbacks._updateTrack(id(track))
    callbacks._setCursor()

def unlinkCurrentBlock():
    currentBlockId = id(session.data.currentTrack().currentBlock())
    unlinkBlock(currentBlockId)

def unlinkBlock(blockId):
    track, block = session.data.blockById(blockId)
    newData = block.getUnlinkedData()
    assert newData
    _setBlockData(block, newData) #handles undo and callbacks

def _setBlockData(block, newData):
    session.history.register(lambda bl=block, old=block.data: _setBlockData(bl, old), descriptionString = "set block data")
    block.data = newData
    #no callbacks needed.


#Cursor
def left():
    """move the currently active tracks cursor one position to the left.
    Can be directly used by a user interface"""
    session.data.currentTrack().left()
    callbacks._setCursor()

def right():
    """move the currently active tracks cursor one position to the right.
    Can be directly used by a user interface"""
    session.data.currentTrack().right()
    callbacks._setCursor()

def selectLeft():
    session.data.setSelectionBeginning() #or not, if there is already one.
    session.data.currentTrack().left()
    callbacks._setCursor(destroySelection = False)

def selectRight():
    session.data.setSelectionBeginning()
    session.data.currentTrack().right()
    callbacks._setCursor(destroySelection = False)

def measureLeft():
    session.data.currentTrack().measureLeft()
    callbacks._setCursor()

def measureRight():
    session.data.currentTrack().measureRight()
    callbacks._setCursor()

def selectMeasureLeft():
    session.data.setSelectionBeginning()
    session.data.currentTrack().measureLeft()
    callbacks._setCursor(destroySelection = False)

def selectMeasureRight():
    session.data.setSelectionBeginning()
    session.data.currentTrack().measureRight()
    callbacks._setCursor(destroySelection = False)

def measureStart():
    session.data.currentTrack().measureStart()
    callbacks._setCursor(destroySelection = True)

def selectMeasureStart():
    session.data.setSelectionBeginning()
    session.data.currentTrack().measureStart()
    callbacks._setCursor(destroySelection = False)


def blockLeft():
    if session.data.currentTrack().currentBlock().localCursorIndex == 0:
        session.data.currentTrack().left()
    session.data.currentTrack().startOfBlock()
    session.data.currentTrack().left()
    callbacks._setCursor()

def blockRight():
    if session.data.currentTrack().currentBlock().isAppending():
        session.data.currentTrack().right()
    session.data.currentTrack().endOfBlock()
    session.data.currentTrack().right()
    callbacks._setCursor()

def selectBlockLeft():
    if session.data.currentTrack().currentBlock().localCursorIndex == 0:
        session.data.currentTrack().left()
    session.data.setSelectionBeginning()
    session.data.currentTrack().startOfBlock()
    session.data.currentTrack().left()
    callbacks._setCursor(destroySelection = False)

def selectBlockRight():
    if session.data.currentTrack().currentBlock().isAppending():
        session.data.currentTrack().right()
    session.data.setSelectionBeginning()
    session.data.currentTrack().endOfBlock()
    session.data.currentTrack().right()
    callbacks._setCursor(destroySelection = False)

def head():
    session.data.currentTrack().head()
    callbacks._setCursor()

def tail():
    session.data.currentTrack().tail()
    callbacks._setCursor()

def selectHead():
    session.data.setSelectionBeginning()
    session.data.currentTrack().head()
    callbacks._setCursor(destroySelection = False)

def selectTail():
    session.data.setSelectionBeginning()
    session.data.currentTrack().tail()
    callbacks._setCursor(destroySelection = False)

def trackUp():
    session.data.trackUp()
    callbacks._setCursor()

def trackDown():
    session.data.trackDown()
    callbacks._setCursor()

def trackFirst():
    session.data.trackFirst()
    callbacks._setCursor()

def trackLast():
    session.data.trackLast()
    callbacks._setCursor()

def selectTrackUp():
    session.data.setSelectionBeginning()
    session.data.trackUp()
    callbacks._setCursor(destroySelection = False)

def selectTrackDown():
    session.data.setSelectionBeginning()
    session.data.trackDown()
    callbacks._setCursor(destroySelection = False)

def selectTrackFirst():
    session.data.setSelectionBeginning()
    session.data.trackFirst()
    callbacks._setCursor(destroySelection = False)

def selectTrackLast():
    session.data.setSelectionBeginning()
    session.data.trackLast()
    callbacks._setCursor(destroySelection = False)

def selectAllTracks():
    shortestTrack = sorted(session.data.tracks, key = lambda track: track.duration())[0]
    trackIndex = session.data.tracks.index(shortestTrack)
    session.data.goTo(trackIndex, 0, 0) #the position in the track doesn't matter. we just want into the track.
    tail()
    tickindexShortestTrack = session.data.currentTrack().state.tickindex
    #assert session.data.currentTrack().state.tickindex == tickindexShortestTrack == shortestTrack.duration(), (session.data.currentTrack().state.tickindex, tickindexShortestTrack, shortestTrack.duration())
    session.data.trackFirst()
    session.data.currentTrack().head()
    #Create Selection
    session.data.setSelectionBeginning()
    session.data.trackLast()
    session.data.currentTrack().goToTickindex(tickindexShortestTrack)
    callbacks._setCursor(destroySelection = False)

def selectTrack():
    head()
    selectTail()

def selectMeasureColumn():
    measureStart()
    trackFirst()
    measureStart()
    selectMeasureRight()
    selectTrackLast()

def toTickindex(trackid, tickindex, destroySelection = True):
    """Was implemented for mouse clicking in a GUI Score"""
    if tickindex < 0:
        tickindex = 0
        session.data
    trackObject = session.data.trackById(trackid)
    session.data.trackIndex = session.data.tracks.index(trackObject)
    trackObject.goToTickindex(tickindex)
    callbacks._setCursor(destroySelection)

def selectToTickindex(trackid, tickindex):
    session.data.setSelectionBeginning()
    toTickindex(trackid, tickindex, destroySelection = False)

def up():
    session.data.cursor.up()
    callbacks._setCursor(destroySelection = False)
    #this does not create a selection if there was none.
    #You need to call setSelectionBeginning() to start a selection.
    #However, this does modify an existing selection since the cursor value changes

def down():
    session.data.cursor.down()
    callbacks._setCursor(destroySelection = False)

def upOctave():
    session.data.cursor.upOctave()
    callbacks._setCursor(destroySelection = False)

def downOctave():
    session.data.cursor.downOctave()
    callbacks._setCursor(destroySelection = False)

def _delete(backspace = False):
    def undoDelete(deletedItemCopy):
        """We need to go back one position after insert"""
        insertItem(deletedItemCopy)
        left() #sets the cursor

    if backspace:  #this is not in backspace() itself because it disturbs _deleteSelection() when we go left before deleting.
        session.data.currentTrack().left() #does not trigger a callback.

    moveFunction = _createLambdaMoveToForCurrentPosition()
    deletedItemCopy = session.data.currentTrack().delete()  #this is obviously _not_ track-delete but item delete
    if deletedItemCopy: #and not None / appending position
        if backspace:                
            def registeredUndoFunction():            
                moveFunction()
                insertItem(deletedItemCopy)
            session.history.register(registeredUndoFunction, descriptionString = "delete item")
        else:
            def registeredUndoFunction():            
                moveFunction()
                undoDelete(deletedItemCopy)
            session.history.register(registeredUndoFunction, descriptionString = "delete item")
        callbacks._updateChangedTracks()
        callbacks._setCursor()

def backspace():
    """Callback and Undo are done via delete"""
    delete(backspaceForSingleItemDelete = True)

def delete(backspaceForSingleItemDelete = None):
    """Choose wether to delete a single item or a selection.
    Delete selections is tricky thats why this is done not
    in the usual apply-function-to-selection way"""
    if session.data.cursorWhenSelectionStarted:
        _deleteSelection()
    else:
        _delete(backspaceForSingleItemDelete)

#Chose prevailing durations

def prevailingLonga():
    pass #TODO
def prevailingBrevis():