synesthesia benchmarking type declaration

synesthesia-benchmarking.d.ts

type ControlType = 'toggle' | 'bang' | 'slider' | 'knob' | 'dropdown'

interface ControlSetting {
  /**
   * normalized (0-1)
   * The value to test.
   * toggle: <=0.5 = off, >0.5 = on
   * bang: trigger on >0.5
   * dropdown: 1/n*i,
   * - n is the number of items in the dropdown and i is the index of the selected item.
   * - The value will be interpolated as an index to select one of the dropdown options,
   *   in line with Synesthesia's MIDI control of dropdowns
   * */
  value: number | ((i: number) => number)

  /**
   * The type of the control.
   */
  type: ControlType

  /**
   * The type specific index of the control in the scene.
   * E.g. if it's the first slider in the scene, then index would be 0,
   * even if other types of controls precede it.
   * Check the MIDI Panel in Synesthesia to see details.
   * */
  index: number

  /**
   * in ms
   * The duration before the next control setting is tested.
   * If not provided, the test runner tests the control until the FPS
   * has stabilized or reached the tester's system-defined max duration.
   * */
  duration?: number

  /**
   * in hz
   * Toggles or triggers the control at the specified frequency.
   * Only relevant for toggles and bangs.
   */
  frequency?: number
}

interface Song {
  /**
   * Link to the song
   * Supports:
   * Spotify, SoundCloud, YouTube
   * */
  url: string

  /**
   * in seconds
   * Play from this time in the song.
   * */
  start?: number

  /**
   * in seconds
   * Stop at this time in the song. Must be greater than start.
   * */
  end?: number
}

interface Test {
  /**
   * The control options to test.
   * Should only include control settings that affect performance.
   * The tests are combined in a matrix to test all combinations.
   * Methods to pick a subset of the combinations will be added in the future.
   * */
  controlSettings: ControlSetting[]

  /**
   * The songs to play while testing.
   * */
  songs: Song[]

  /**
   * The scene to test.
   * Can not be a URL to prevent malicious code injection.
   * The string must match the name of a .synscene in the scenes directory.
   * You can create a pull request to add a new scene.
   * */
  scene: string

  /**
   * Specifies if the scene is under development.
   * This lets the tester know if the scene is still in development.
   * Testers can opt in to test scenes under development.
   * */
  sceneUnderDevelopment: boolean

  /**
   * The name of the test.
   * This is used to identify the test in the results CSV.
   * */
  name: string

  /**
   * The description of the test.
   * This is used to identify the test in the results CSV.
   * */
  description: string
}