App

In the App component we organize and store all the data that is crucial to the tracks as well as some of the other components. This type of data is called global data or global values. Let's habe a look at some of the most important one's.

// Tracks
const [tracks, setTracks] = useState([
    {
        trackID: nanoid(),
        trackIndex: 0,
        channelIndex: null,
        visible: true,
        audioID: null,
        filename: null,
        audioDuration: null,
        frequencies: null,
        spectrogram: null,
    }
])
const tracksRef = useRef(tracks);

Inside the tracks state variable we store a an array of track objects. On the first render of the app start with one empty track. As you can see, most values are empty. Later, when we render the JSX returned by the App component, we will iterate over this array and feed this data to create instances of the track component.

tracks.ref is an exact copy of the tracks variable. We use a reference object so that some of the useEffect Hooks that set up event listeners (such as the close tab or key-inputs) can always work with the current version of the tracks variable.

// Audio Sync
const [globalAudioDuration, setGlobalAudioDuration] = useState(null)
const [globalClipDuration, setGlobalClipDuration] = useState(null)
const [currentStartTime, setCurrentStartTime] = useState(0)
const [currentEndTime, setCurrentEndTime] = useState(0)
const [maxScrollTime, setMaxScrollTime] = useState(0)
const [scrollStep, setScrollStep] = useState(0)
const [globalHopLength, setGlobalHopLength] = useState('')
const [globalNumSpecColumns, setGlobalNumSpecColumns] = useState('')
const [globalSamplingRate, setGlobalSamplingRate] = useState('')

Here we have all the variables that store information about the syncing of the different audio tracks. Since we can have multiple tracks of different lengths, it is crucial we keep track of these values globally in our app component, to prevent the audio tracks from desyncing. The longest audio track always dictates the all of these values, the shorter tracks. For example, if the user uploads two audio files, one 7 seconds long and the other 20 seconds long, the global audio duration will be 20 seconds, for all tracks.

globalAudioDuration The duration of the longest audio track

globalClipDuration The duration of the audio in the current viewport

currentStartTime The current start time of the audio in the current viewport

currentEndTime The current end time of the audio in the current viewport

maxScrollTime The maximum time we can scroll towards. For instance when we're fully zoomed out, we can not scroll anywhere anymore, so the maximum scroll time will be 0.

scrollStep The value by which currentStartTime and currentEndTime will increase or decrease when scrolling left or right respectively.

globalHopLength, globalNumSpecColumns, and globalSamplingRate are values that are computed by the backend. The user can manipulate these alternatively to adjust the zoom level and the view of the spectrogram. Together they're in direct relation to the global audio duration through the formula: globalAudioDuration >= HopLength / SamplingRate * NumSpecColumns

// Global Configurations
const [defaultConfig, setDefaultConfig] = useState(null)
const [showGlobalConfigWindow, setShowGlobalConfigWindow] = useState(false)

defaultConfig saves the initial values of globalHopLength, globalNumSpecColumns, and globalSamplingRate returned by the backend, so the user can return to them.

showGlobalConfigWindow controls the visibility of that input window, in which users can change those three values.

// Labels import/export
const [importedLabels, setImportedLabels] = useState(null)
const [allLabels, setAllLabels] = useState([])
const [exportRequest, setExportRequest] = useState(false)
const [submitRequest, setSubmitRequest] = useState(false)

importedLabels stores the labels that have been uploaded either manually by the user providing a CSV file or automatically through from one of the database endpoints.

allLabels stores all labels of all tracks.

exportRequest is set to true when the user clicks on the download CSV button. This will collect all labels from all tracks and store them in allLabels, then initiate the download process.

submitRequest is set to true when the user clicks on the submit button. This will collect all labels from all tracks and store them in allLabels, then initiate the submit p

// Strict Mode
const [strictMode, setStrictMode] = useState(false)
const [annotationInstance, setAnnotationInstance] = useState(null)

strictMode is a boolean that is optionally passed as a url parameter (strict-mode=true). When it is set to true, will run the application in a mode with limited functionalities and features.

annotationInstance stores an identifier that is being passed from the metadata object, also as a url parameter (either metadata or hash-id).

// Audio upload
const [filesUploading, setFilesUploading] = useState(false);
const [uploadProgress, setUploadProgress] = useState(0);

filesUploading is a simple boolean that, wen set to true, conditionally renders a loading circle while audio files are being uploaded to the backend server.

uploadProgess is the value that appears inside the loading circle.

// Species Array
const [speciesArray, setSpeciesArray] = useState(() => {
    const annotatedAreaIndividual = new Individual(nanoid(), ANNOTATED_AREA_INDIVIDUAL)
    const annotatedAreaClustername = new Clustername(nanoid(), ANNOTATED_AREA_CLUSTERNAME, ANNOTATED_AREA_COLOR)
    annotatedAreaIndividual.isActive = false
    annotatedAreaClustername.isActive = false
    const annotatedAreaLabel = new Species(nanoid(), ANNOTATED_AREA, [annotatedAreaIndividual],  [annotatedAreaClustername])

    const newIndividual = new Individual(nanoid(), UNKNOWN_INDIVIDUAL)
    const newClustername = new Clustername(nanoid(), UNKNOWN_CLUSTERNAME, DEFAULT_UNKNOWN_CLUSTERNAME_COLOR)
    const newSpecies = new Species(nanoid(),UNKNOWN_SPECIES, [newIndividual], [newClustername] )

    return [newSpecies, annotatedAreaLabel]
})
const [deletedItemID, setDeletedItemID] = useState(null)

speciesArray holds the species objects of the child component SpeciesMenu.jsx.

deletedItemID tracks the ID of an item (species, individual or clustername) that the user deleted. It s then passed to all children Track.jsx components, to remove any annotations made with that item.

// WhisperSeg
const [tokenInference, setTokenInference] = useState('')
const [tokenFinetune, setTokenFinetune] = useState('')

tokenInference and tokenFinetune hold the authentication tokens that users can input to access the different WhisperSeg API endpoints.

// Keyboard Interactions
const [leftArrowKeyPressed, setLeftArrowKeyPressed] = useState(false)
const [rightArrowKeyPressed, setRightArrowKeyPressed] = useState(false)

leftArrowKeyPressed and rightArrowKeyPressed track the state of the user's arrow keys, which the user can use to scroll through the audio.

// Keep track of Open Windows
const {anyWindowsOpen} = useOpenWindowsContext()

anyWindowsOpen tracks the current value of the OpenWindowsContext object defined in OpenWindowsContext.jsx. This variable tracks all open windows in the track components and is used to disable the arrow key scroll events when any windows are open, so the user doesn't scroll by accident when's writing inside input boxes.