Package com.bitwig.extension.controller.api

Interface Clip

All Superinterfaces:
ObjectProxy, Subscribable
All Known Subinterfaces:
CursorClip, PinnableCursorClip
public interface Clip extends ObjectProxy
An interface that provides access to the contents of a clip in Bitwig Studio. The note content of the clip is exposed in terms of steps and keys, mainly targeted to x-y-grid applications such as step sequencers.
Since:
API version 1

  • Method Details

    • scrollToKey

      void scrollToKey(int key)
      Scroll the note grid so that the given key becomes the key with y position of 0. Note: This can cause some parts of the grid to represent invalid keys as there is no clipping
      Parameters:
      key - the key that should be the new key with a y position of 0. This must be a value in the range 0...127.
      Since:
      API version 1

    • scrollKeysPageUp

      void scrollKeysPageUp()
      Scrolls the note grid keys one page up. For example if the note grid is configured to show 12 keys and is currently showing keys [36..47], calling this method would scroll the note grid to key range [48..59].
      Since:
      API version 1

    • scrollKeysPageDown

      void scrollKeysPageDown()
      Scrolls the note grid keys one page down. For example if the note grid is configured to show 12 keys and is currently showing keys [36..47], calling this method would scroll the note grid to key range [48..59].
      Since:
      API version 1

    • scrollKeysStepUp

      void scrollKeysStepUp()
      Scrolls the note grid keys one key up. For example if the note grid is configured to show 12 keys and is currently showing keys [36..47], calling this method would scroll the note grid to key range [37..48].
      Since:
      API version 1

    • scrollKeysStepDown

      void scrollKeysStepDown()
      Scrolls the note grid keys one key down. For example if the note grid is configured to show 12 keys and is currently showing keys [36..47], calling this method would scroll the note grid to key range [35..46].
      Since:
      API version 1

    • scrollToStep

      void scrollToStep(int step)
      Scroll the note grid so that the given step becomes visible.
      Parameters:
      step - the step that should become visible
      Since:
      API version 1

    • scrollStepsPageForward

      void scrollStepsPageForward()
      Scrolls the note grid steps one page forward. For example if the note grid is configured to show 16 steps and is currently showing keys [0..15], calling this method would scroll the note grid to key range [16..31].
      Since:
      API version 1

    • scrollStepsPageBackwards

      void scrollStepsPageBackwards()
      Scrolls the note grid steps one page backwards. For example if the note grid is configured to show 16 steps and is currently showing keys [16..31], calling this method would scroll the note grid to key range [0..16].
      Since:
      API version 1

    • scrollStepsStepForward

      void scrollStepsStepForward()
      Scrolls the note grid steps one step forward. For example if the note grid is configured to show 16 steps and is currently showing keys [0..15], calling this method would scroll the note grid to key range [1..16].
      Since:
      API version 1

    • scrollStepsStepBackwards

      void scrollStepsStepBackwards()
      Scrolls the note grid steps one step backwards. For example if the note grid is configured to show 16 steps and is currently showing keys [1..16], calling this method would scroll the note grid to key range [0..15].
      Since:
      API version 1

    • canScrollKeysUp

      BooleanValue canScrollKeysUp()
      Value that reports if the note grid keys can be scrolled further up.
      Since:
      API version 2

    • addCanScrollKeysUpObserver

      @Deprecated void addCanScrollKeysUpObserver(BooleanValueChangedCallback callback)
      Deprecated.
      Use canScrollKeysUp() instead.
      Registers an observer that reports if the note grid keys can be scrolled further up.
      Parameters:
      callback - a callback function that receives a single boolean parameter.
      Since:
      API version 1

    • canScrollKeysDown

      BooleanValue canScrollKeysDown()
      Value that reports if the note grid keys can be scrolled further down.
      Since:
      API version 2

    • addCanScrollKeysDownObserver

      @Deprecated void addCanScrollKeysDownObserver(BooleanValueChangedCallback callback)
      Deprecated.
      Use canScrollKeysDown() instead.
      Registers an observer that reports if the note grid keys can be scrolled further down.
      Parameters:
      callback - a callback function that receives a single boolean parameter.
      Since:
      API version 1

    • canScrollStepsBackwards

      BooleanValue canScrollStepsBackwards()
      Value that reports if the note grid if the note grid steps can be scrolled backwards.
      Since:
      API version 2

    • addCanScrollStepsBackwardsObserver

      @Deprecated void addCanScrollStepsBackwardsObserver(BooleanValueChangedCallback callback)
      Deprecated.
      Use canScrollStepsBackwards() instead.
      Registers an observer that reports if the note grid steps can be scrolled backwards.
      Parameters:
      callback - a callback function that receives a single boolean parameter.
      Since:
      API version 1

    • canScrollStepsForwards

      BooleanValue canScrollStepsForwards()
      Value that reports if the note grid if the note grid steps can be scrolled forwards.
      Since:
      API version 2

    • addCanScrollStepsForwardObserver

      @Deprecated void addCanScrollStepsForwardObserver(BooleanValueChangedCallback callback)
      Deprecated.
      Use canScrollStepsForwards() instead.
      Registers an observer that reports if the note grid keys can be scrolled forward.
      Parameters:
      callback - a callback function that receives a single boolean parameter.
      Since:
      API version 1

    • toggleStep

      void toggleStep(int x, int y, int insertVelocity)
      Since:
      API version 1
      See Also:

    • toggleStep

      void toggleStep(int channel, int x, int y, int insertVelocity)
      Toggles the existence of a note in the note grid cell specified by the given x and y arguments.
      Parameters:
      channel - the MIDI channel, between 0 and 15.
      x - the x position within the note grid, defining the step/time of the target note
      y - the y position within the note grid, defining the key of the target note
      insertVelocity - the velocity of the target note in case a new note gets inserted
      Since:
      API version 10

    • setStep

      void setStep(int x, int y, int insertVelocity, double insertDuration)
      Since:
      API version 1
      See Also:

    • setStep

      void setStep(int channel, int x, int y, int insertVelocity, double insertDuration)
      Creates a note in the grid cell specified by the given x and y arguments. Existing notes are overwritten.
      Parameters:
      x - the x position within the note grid, defining the step/time of the new note
      y - the y position within the note grid, defining the key of the new note
      insertVelocity - the velocity of the new note
      insertDuration - the duration of the new note
      Since:
      API version 1

    • clearStep

      void clearStep(int x, int y)
      Since:
      API version 1
      See Also:

    • clearStep

      void clearStep(int channel, int x, int y)
      Removes the note in the grid cell specified by the given x and y arguments. Calling this method does nothing in case no note exists at the given x-y-coordinates.
      Parameters:
      channel - MIDI channel, from 0 to 15.
      x - the x position within the note grid, defining the step/time of the target note
      y - the y position within the note grid, defining the key of the target note
      Since:
      API version 10

    • clearStepsAtX

      void clearStepsAtX(int channel, int x)
      Removes all notes in the grid started on the step x.
      Since:
      API version 10

    • clearSteps

      @Deprecated void clearSteps(int y)
      Deprecated.
      Use clearStepsAtY(int, int) instead.
      Since:
      API version 1
      See Also:

    • clearStepsAtY

      void clearStepsAtY(int channel, int y)
      Removes all notes in the grid row specified by the given y argument.
      Parameters:
      channel - MIDI channel, from 0 to 15.
      y - the y position within the note grid, defining the key of the target note
      Since:
      API version 10

    • clearSteps

      void clearSteps()
      Removes all notes in the grid.
      Since:
      API version 1

    • moveStep

      void moveStep(int x, int y, int dx, int dy)
      Since:
      API version 16
      See Also:

    • moveStep

      void moveStep(int channel, int x, int y, int dx, int dy)
      Moves a note in the note grid cell specified by the given x and y arguments to the grid cell (x + dx, y + dy).
      Parameters:
      channel - MIDI channel, from 0 to 15.
      x - the x position within the note grid, defining the step/time of the target note
      y - the y position within the note grid, defining the key of the target note
      dx - the offset in x direction
      dy - the offset in y direction
      Since:
      API version 16

    • selectStepContents

      void selectStepContents(int x, int y, boolean clearCurrentSelection)
      Since:
      API version 1
      See Also:

    • selectStepContents

      void selectStepContents(int channel, int x, int y, boolean clearCurrentSelection)
      Selects the note in the grid cell specified by the given x and y arguments, in case there actually is a note at the given x-y-coordinates.
      Parameters:
      channel - MIDI channel, from 0 to 15.
      x - the x position within the note grid, defining the step/time of the target note
      y - the y position within the note grid, defining the key of the target note
      clearCurrentSelection - `true` if the existing selection should be cleared, false if the note should be added to the current selection.
      Since:
      API version 10

    • setStepSize

      void setStepSize(double lengthInBeatTime)
      Sets the beat time duration that is represented by one note grid step.
      Parameters:
      lengthInBeatTime - the length of one note grid step in beat time.
      Since:
      API version 1

    • addStepDataObserver

      void addStepDataObserver(StepDataChangedCallback callback)
      Registers an observer that reports which note grid steps/keys contain notes.
      Parameters:
      callback - A callback function that receives three parameters: 1. the x (step) coordinate within the note grid (integer), 2. the y (key) coordinate within the note grid (integer), and 3. an integer value that indicates if the step is empty (`0`) or if a note continues playing (`1`) or starts playing (`2`).
      Since:
      API version 1
      See Also:

    • addNoteStepObserver

      void addNoteStepObserver(NoteStepChangedCallback callback)
      Registers an observer that reports which note grid steps/keys contain notes.
      Parameters:
      callback - A callback function that receives the StepInfo.
      Since:
      API version 10

    • playingStep

      IntegerValue playingStep()
      Value that reports note grid cells as they get played by the sequencer.
      Since:
      API version 2

    • addPlayingStepObserver

      @Deprecated void addPlayingStepObserver(IntegerValueChangedCallback callback)
      Deprecated.
      Use playingStep() instead.
      Registers an observer that reports note grid cells as they get played by the sequencer.
      Parameters:
      callback - A callback function that receives a single integer parameter, which reflects the step coordinate that is played, or -1 if no step is associated with the current playback position.
      Since:
      API version 1

    • setName

      void setName(String name)
      Updates the name of the clip.
      Parameters:
      name - the new clip name
      Since:
      API version 1

    • getShuffle

      SettableBooleanValue getShuffle()
      Returns shuffle settings of the clip.
      Returns:
      the value object that represents the clips shuffle setting.
      Since:
      API version 1

    • getAccent

      SettableRangedValue getAccent()
      Returns accent setting of the clip.
      Returns:
      the ranged value object that represents the clips accent setting.
      Since:
      API version 1

    • getPlayStart

      SettableBeatTimeValue getPlayStart()
      Returns the start of the clip in beat time.
      Returns:
      the beat time object that represents the clips start time.
      Since:
      API version 1

    • getPlayStop

      SettableBeatTimeValue getPlayStop()
      Returns the length of the clip in beat time.
      Returns:
      the beat time object that represents the duration of the clip.
      Since:
      API version 1

    • isLoopEnabled

      SettableBooleanValue isLoopEnabled()
      Returns an object that provides access to the loop enabled state of the clip.
      Returns:
      a boolean value object.
      Since:
      API version 1

    • getLoopStart

      SettableBeatTimeValue getLoopStart()
      Returns the loop start time of the clip in beat time.
      Returns:
      the beat time object that represents the clips loop start time.
      Since:
      API version 1

    • getLoopLength

      SettableBeatTimeValue getLoopLength()
      Returns the loop length of the clip in beat time.
      Returns:
      the beat time object that represents the clips loop length.
      Since:
      API version 1

    • addColorObserver

      @Deprecated void addColorObserver(ColorValueChangedCallback callback)
      Deprecated.
      use color() instead.
      Registers an observer that reports the clip color.
      Parameters:
      callback - a callback function that receives three parameters: 1. the red coordinate of the RBG color value, 2. the green coordinate of the RBG color value, and 3. the blue coordinate of the RBG color value
      Since:
      API version 1

    • color

      SettableColorValue color()
      Get the color of the clip.
      Since:
      API version 2

    • duplicate

      void duplicate()
      Duplicates the clip.
      Since:
      API version 1

    • duplicateContent

      void duplicateContent()
      Duplicates the content of the clip.
      Since:
      API version 1

    • transpose

      void transpose(int semitones)
      Transposes all notes in the clip by the given number of semitones.
      Parameters:
      semitones - the amount of semitones to transpose, can be a positive or negative integer value.
      Since:
      API version 1

    • quantize

      void quantize(double amount)
      Quantize the start time of all notes in the clip according to the given amount. The note lengths remain the same as before.
      Parameters:
      amount - a factor between `0` and `1` that allows to morph between the original note start and the quantized note start.
      Since:
      API version 1

    • getTrack

      Track getTrack()
      Gets the track that contains the clip.
      Returns:
      a track object that represents the track which contains the clip.
      Since:
      API version 1

    • launchQuantization

      SettableEnumValue launchQuantization()
      Setting for the default launch quantization. Possible values are "default", "none", "8", "4", "2", "1", "1/2", "1/4", "1/8", "1/16"
      Since:
      API version 8

    • useLoopStartAsQuantizationReference

      SettableBooleanValue useLoopStartAsQuantizationReference()
      Setting "Q to loop" in the inspector.
      Since:
      API version 8

    • launchLegato

      @Deprecated SettableBooleanValue launchLegato()
      Deprecated.
      Use launchMode() instead.
      Setting "Legato" from the inspector.
      Since:
      API version 8

    • launchMode

      SettableEnumValue launchMode()
      Setting "Launch Mode" from the inspector. Possible values are: - default - from_start - continue_or_from_start - continue_or_synced - synced
      Since:
      API version 9

    • getStep

      NoteStep getStep(int channel, int x, int y)
      Get step info
      Since:
      API version 10

    • launch

      void launch()
      Launches the clip.
      Since:
      API version 10

    • launchWithOptions

      void launchWithOptions(String quantization, String launchMode)
      Launches with the given options:
      Parameters:
      quantization - possible values are "default", "none", "8", "4", "2", "1", "1/2", "1/4", "1/8", "1/16"
      launchMode - possible values are: "default", "from_start", "continue_or_from_start", "continue_or_synced", "synced"
      Since:
      API version 16

    • clipLauncherSlot

      ClipLauncherSlot clipLauncherSlot()
      Get the clip launcher slot containing the clip.
      Since:
      API version 10

    • showInEditor

      void showInEditor()
      Open the detail editor and show the clip.
      Since:
      API version 18