Renoise Scripting

https://renoise.github.io/xrnx
Admin
Renoise Scripting guide and API documentation for developers writing Lua scripts and tools for the...
Tokens:297,260
Snippets:3,260
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Debug Script with Breakpoints and Evaluation

Source: https://renoise.github.io/xrnx/start/debugging.html

This example demonstrates starting a debug session, defining a function, executing it, and then stopping the debugger. It also shows how to interact with the debugger by evaluating expressions and changing variable values.

```lua
debug.start()

local function sum(a, b)
    return a + b
end

local c = sum(1, 2)
print(c)

debug.stop()

```

--------------------------------

### install_tool

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Application.html

Install order update a tool. Any errors are shown to the user during installation. Installing an already existing tool will upgrade the tool without confirmation. Upgraded tools will automatically be re-enabled, if necessary.

```APIDOC
## install_tool

### Description
Install or update a tool. Any errors are shown to the user during installation. Installing an already existing tool will upgrade the tool without confirmation. Upgraded tools will automatically be re-enabled, if necessary.

### Parameters
- **file_path** (`string`) - The path to the tool's installation file.
```

--------------------------------

### start()

Source: https://renoise.github.io/xrnx/API/modules/debug.html

Starts a debug session by launching the debugger controller and breaking script execution. This is a shortcut for `remdebug.session.start()`.

```APIDOC
## start()

### Description
Shortcut to `remdebug.session.start()`, which starts a debug session: launches the debugger controller and breaks script execution. See "Debugging.md" in the documentation root folder for more info.

### Method
```
start()
```
```

--------------------------------

### BitmapMode

Source: https://renoise.github.io/xrnx/API/renoise/renoise.ViewBuilder.html

Setup how the bitmap should be drawn, recolored.

```APIDOC
## BitmapMode

### Description
Setup how the bitmap should be drawn, recolored. Available modes are:

### Type
`BitmapMode?`
```

--------------------------------

### Create a Simple Dialog with ViewBuilder

Source: https://renoise.github.io/xrnx/guide/tool.html

Instantiate a ViewBuilder and use it to construct a simple dialog with text content. This example demonstrates basic column stacking and styling.

```lua
local vb = renoise.ViewBuilder()

local dialog_title = "Hello World"
local dialog_buttons = { "OK" }

local DEFAULT_MARGIN = renoise.ViewBuilder.DEFAULT_CONTROL_MARGIN

local dialog_content = vb:column {
  margin = DEFAULT_MARGIN,
  views = {
    vb:column {
      style = "group",
      margin = DEFAULT_MARGIN,
      views = {
        vb:text {
          text = "from the Renoise Scripting API\n" ..
                 "in a vb:column with a background."
        },
      }
    }
  }
}

renoise.app():show_custom_prompt(
  dialog_title, dialog_content, dialog_buttons)

```

--------------------------------

### Value Notifier Setup

Source: https://renoise.github.io/xrnx/API/renoise/renoise.ViewBuilder.html

Set up a value notifier that will be called whenever the value changes.

```APIDOC
## Value Notifier Setup

### Description
Configures a callback function to be executed whenever the view's value is modified.

### Parameters
#### Path Parameters
- **notifier** (function | table | userdata) - Required - The notifier function or object to be called when the value changes.
```

--------------------------------

### Select Specific Pattern Lines and Tracks

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Song.html

Select a range of lines and specify the start and end tracks for the selection. This example selects lines 1 to 4 in the first track.

```Lua
renoise.song().selection_in_pattern =
  { start_line = 1, start_track = 1, end_line = 4, end_track = 1 }
```

--------------------------------

### Creating Nested Views (Column Example)

Source: https://renoise.github.io/xrnx/API/renoise/renoise.ViewBuilder.html

Illustrates how to create a `column` view and populate it with nested `text` views, demonstrating the `views` property for child elements.

```APIDOC
## Creating Nested Views (Column Example)

### Description
This example demonstrates the creation of a `column` view with a specified margin and includes two nested `text` views. The `views` property is used to define child elements within a container view.

### Method
`vb:column(properties)`

### Endpoint
N/A (Lua API)

### Parameters
- `properties` (table): A table containing properties for the column view and its children.
  - `margin` (integer): Optional. The margin for the column view.
  - `views` (table): A table containing child views to be added to the column.
    - Each element in `views` can be a call to another `vb` method (e.g., `vb:text(...)`).

### Request Example
```lua
-- creates a column view with `margin = 1` and adds two text views to the column.
vb:column {
  margin = 1,
  views = {
    vb:text {
      text = "Text1"
    },
    vb:text {
      text = "Text1"
    }
  }
}
```

### Response
N/A (Lua API returns objects)

### Success Response (200)
N/A

### Response Example
N/A
```

--------------------------------

### Example Pattern Line Notifier Callback

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Pattern.html

This is an example of a callback function that can be registered to be notified when a pattern's lines change. The 'pos' argument contains details about the location of the change.

```Lua
function my_pattern_line_notifier(pos)
  -- check pos.pattern, pos.track, pos.line (all are indices)
end
```

--------------------------------

### Lua Text Alignment Example

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Views.TextLink.html

Example demonstrating how to set text alignment in Lua. The default is 'left'.

```lua
-- Setup the text's alignment. Applies only when the view's size is larger than
-- the needed size to draw the text
TextAlignment:
    | "left" -- (Default) 
    | "right" -- aligned to the right
    | "center" -- center text
```

--------------------------------

### Create a UDP OSC Client in Renoise

Source: https://renoise.github.io/xrnx/guide/osc.html

This example demonstrates how to create a UDP client to send OSC messages to a server. It shows how to construct and send simple messages, messages with arguments, and bundles of messages.

```lua
-- Create some shortcuts
local OscMessage = renoise.Osc.Message
local OscBundle = renoise.Osc.Bundle

-- Create a client to send messages to the server
local client, socket_error = renoise.Socket.create_client(
  "localhost", 8008, renoise.Socket.PROTOCOL_UDP)
   
if (socket_error) then 
  renoise.app():show_warning(("Failed to start the " .. 
    "OSC client. Error: '%s'"):format(socket_error))
  return
end

-- Construct and send a simple message
client:send(
  OscMessage("/transport/start"):to_binary_data()
)

-- Construct and send a message with arguments
client:send(
  OscMessage("/transport/bpm", { 
    { tag = "f", value = 127.5 } 
  }):to_binary_data()
)

-- Construct and send a bundle of messages
local message1 = OscMessage("/some/message")
local message2 = OscMessage("/another/one", { 
  { tag = "b", value = "with some blob data" },
  { tag = "s", value = "and a string" } 
})

client:send(
  OscBundle(os.clock(), { message1, message2 }):to_binary_data()
)

-- Close the client when done
client:close()

```

--------------------------------

### Renoise Tool Manifest Example

Source: https://renoise.github.io/xrnx/start/tool.html

The manifest.xml file describes your tool to Renoise, including its ID, version, author, and other metadata. Ensure the Id matches the tool's folder name exactly.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<RenoiseScriptingTool doc_version="0">
  <!-- REQUIRED -->
  <Id>com.yourDomain.HelloWorld</Id>
  <ApiVersion>6.2</ApiVersion>
  <Version>1.02</Version>
  <Author>Your Name [your@email.com]</Author>
  <Name>Hello World</Name>
  <!-- OPTIONAL -->
  <Category>Development, Workflow</Category>
  <Description>
    This tool is for printing &quot;Hello World!&quot; to the terminal when loaded.
  </Description>
  <Platform>Windows, Mac, Linux</Platform>
  <License>MIT</License>
  <LicensePath>LICENSE.md</LicensePath>
  <ThumbnailPath>images/thumbnail.png</ThumbnailPath>
  <CoverPath>images/cover.png</CoverPath>
  <DocumentationPath>docs/README.md</DocumentationPath>
  <Homepage>https://some.url/my-tool</Homepage>
  <Documentation>https://some.url/my-tool-docs</Documentation>
  <Discussion>https://some.url/my-tool</Discussion>
  <Repository>https://git.some.url/my-tool</Repository>
  <Donate>https://some.url/donate</Donate>
</RenoiseScriptingTool>
```

--------------------------------

### Fullscreen Property

Source: https://renoise.github.io/xrnx/API/renoise/renoise.ApplicationWindow.html

Get or set the fullscreen state of the Renoise application window.

```Lua
-- Get/set if the application is running fullscreen.
renoise.application().window.fullscreen
```

--------------------------------

### Start Remdebug Controller

Source: https://renoise.github.io/xrnx/start/debugging.html

Launch the remdebug controller script from your system's command line. This prepares the environment to receive debugger connections.

```bash
lua RENOISE_RESOURCE_FOLDER/Scripts/Libraries/remdebug/controller.lua
```

--------------------------------

### Get Platform Information

Source: https://renoise.github.io/xrnx/API/modules/os.html

Returns the platform the script is running on. Possible values are "WINDOWS", "MACINTOSH", or "LINUX".

```lua
return platform()
```

--------------------------------

### prompt_for_filename_to_write

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Application.html

Open a modal dialog to get a filename and path for writing. When an existing file is selected, the dialog will ask whether or not to overwrite it, so you don't have to take care of this on your own.

```APIDOC
## prompt_for_filename_to_write

### Description
Open a modal dialog to get a filename and path for writing. When an existing file is selected, the dialog will ask whether or not to overwrite it, so you don't have to take care of this on your own.

### Parameters
- **file_extension** (`string`) - The default file extension for the file.
- **title** (`DialogTitle`) - The title of the dialog.

### Returns
- **path** (`string`) - The path for the file to write.
```

--------------------------------

### Start Remote Debugging Session

Source: https://renoise.github.io/xrnx/start/debugging.html

Call `debug.start()` to initiate a debugging session. This opens a separate debugger controller window and immediately pauses script execution, allowing for step-by-step debugging.

```lua
-- Opens a debugger controller in a new terminal/cmd window and
-- attaches the debugger to this script. Immediately breaks execution.
debug.start()

```

--------------------------------

### ViewBuilder Initialization and Basic Usage

Source: https://renoise.github.io/xrnx/API/renoise/renoise.ViewBuilder.html

Demonstrates how to create a ViewBuilder instance and add a simple button, showing both inline property setting and separate configuration.

```APIDOC
## ViewBuilder Initialization and Basic Usage

### Description
This section shows how to initialize the `ViewBuilder` and add basic UI elements like buttons. It illustrates two ways to configure properties: directly within the creation call or by assigning them to the created view object afterwards.

### Method
`renoise.ViewBuilder()`

### Endpoint
N/A (Lua API)

### Parameters
None for initialization.

### Request Example
```lua
-- Create a new ViewBuilder instance
local vb = renoise.ViewBuilder()

-- Add a button with text set inline
vb:button { text = "ButtonText" }

-- Equivalent to:
local my_button = vb:button()
my_button.text = "ButtonText"
```

### Response
N/A (Lua API returns objects)

### Success Response (200)
N/A

### Response Example
N/A
```

--------------------------------

### SampleLfoModulationDevice Functions

Source: https://renoise.github.io/xrnx/API/renoise/renoise.SampleLfoModulationDevice.html

Provides functions to initialize the device, copy settings from another device, and access individual parameters by index.

```APIDOC
## Functions

### `init(self)`
Reset the device to its default state.

### `copy_from(self, other_device : renoise.SampleModulationDevice)`
Copy a device's state from another device. 'other_device' must be of the same type.

### `parameter(self, index : integer) -> renoise.DeviceParameter`
Access to a single parameter by index. Use properties 'parameters' to iterate over all parameters and to query the parameter count.
```

--------------------------------

### Editable Text Field Example

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Views.TextField.html

A basic representation of an editable text field. This is a visual example and not executable code.

```text
 +----------------+
 | Editable Te|xt |
 +----------------+ 
```

--------------------------------

### Configure and Start Remote Debugging Engine

Source: https://renoise.github.io/xrnx/start/debugging.html

Configure the remdebug engine to connect to a remote controller and then start the debugging session. Ensure the host and port match the controller's configuration.

```lua
require "remdebug.engine"
-- default config is "localhost" on port 8171
remdebug.engine.configure { host = "some_host", port = 1234 }
remdebug.engine.start()
```

--------------------------------

### Create and Configure a Button with ViewBuilder

Source: https://renoise.github.io/xrnx/API/renoise/renoise.ViewBuilder.html

Demonstrates creating a new ViewBuilder instance and adding a button with its text property set. This is equivalent to creating the button and then setting its properties individually.

```lua
local vb = renoise.ViewBuilder()
-- create a new ViewBuilder
vb:button { text = "ButtonText" } -- is the same as
my_button = vb:button(); my_button.text = "ButtonText"
```

--------------------------------

### Custom Tuning Example

Source: https://renoise.github.io/xrnx/API/renoise/renoise.InstrumentTriggerOptions.html

Applies a custom tuning to an instrument using an array of pitch values. This example uses Andreas Werckmeister's well-tempered tuning. Setting a custom tuning disables MTS ESP tuning.

```lua
-- Andreas Werckmeister's temperament III (the most famous one, 1681)
local well_tempered_tuning = {
  256/243, 1.117403, 32/27, 1.252827, 4/3, 1024/729,
  1.494927, 128/81, 1.670436, 16/9, 1.879241, 2/1
}
instrument.tuning = well_tempered_tuning
```

--------------------------------

### Initialize SampleFaderModulationDevice

Source: https://renoise.github.io/xrnx/API/renoise/renoise.SampleFaderModulationDevice.html

Resets the device to its default state. This function is part of the device's lifecycle.

```Lua
init(self)
```

--------------------------------

### Access Pattern Sequence Sections

Source: https://renoise.github.io/xrnx/API/renoise/renoise.PatternSequencer.html

Provides access to pattern sequence sections. A section is defined from a sequence position with the `is_start_of_section` flag set, to the next position that also starts a section, or to the end of the song if no other section start is found.

```APIDOC
## Access Pattern Sequence Sections

### Description
Access to pattern sequence sections. When the `is_start_of_section` flag is set for a sequence position, a section ranges from this position to the next position which starts a section, or till the end of the song when there are no others.

### Method
Implicit (likely a method call on the sequencer object)

### Parameters
* **sequence_index** (integer) - Description of the sequence index parameter.
* **is_start_of_section** (boolean) - Flag indicating if this position starts a section.
```

--------------------------------

### Create and Assign Tool Preferences

Source: https://renoise.github.io/xrnx/guide/tool.html

Create a `renoise.Document` with default observable preferences and assign it to the tool. This document will be automatically saved to `preferences.xml`.

```lua
local options = renoise.Document.create("RandomizerToolPreferences") {
  randomize_bpm = true,
  randomize_tracks = false,
  max_tracks = 16
}

renoise.tool().preferences = options
```

--------------------------------

### ButtonStyle

Source: https://renoise.github.io/xrnx/API/renoise/renoise.ViewBuilder.html

Gets or sets the visual style of a button.

```APIDOC
ButtonStyle:
    ?
> Get/set the style a button should be displayed with.
```

--------------------------------

### move_to

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Views.Canvas.Context.html

Creates a new subpath starting at the specified coordinates.

```APIDOC
## move_to

### Description
Create a new subpath. The given point will become the first point of the new subpath and is subject to the current transform at the time this is called.

### Method
Implicit (called on the context object)

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
- **x** (number) - Required - The x-coordinate of the starting point.
- **y** (number) - Required - The y-coordinate of the starting point.
```

--------------------------------

### PlayMode Enum

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Transport.html

Defines the playback modes for starting the transport.

```APIDOC
## PlayMode Enum

> ```lua
> __
> {
>     PLAYMODE_RESTART_PATTERN: integer = 1,
>     PLAYMODE_CONTINUE_PATTERN: integer = 2,
> }
> 
> ```
```

--------------------------------

### Build Views Step-by-Step with ViewBuilder

Source: https://renoise.github.io/xrnx/guide/tool.html

Demonstrates building GUI elements incrementally and using unique IDs to reference views for dynamic updates. This is useful for complex layouts where direct manipulation of widgets is needed.

```lua
local vb = renoise.ViewBuilder()

local my_column_view = vb:column{}
my_column_view.margin = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN
my_column_view.style = "group"

local my_text_view = vb:text{}
my_text_view.text = "My text"
my_column_view:add_child(my_text_view)

local my_column_view_nested = vb:column {
  margin = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN,
  style = "group",
  views = {
    vb:text {
      text = "My text"
    }
  }
}

local DEFAULT_DIALOG_MARGIN = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN
local DEFAULT_CONTROL_SPACING = renoise.ViewBuilder.DEFAULT_CONTROL_SPACING

local dialog_title = "ViewBuilder IDs"
local dialog_buttons = {"OK"}

local dialog_content = vb:column {
  margin = DEFAULT_DIALOG_MARGIN,
  spacing = DEFAULT_CONTROL_SPACING,
  views = {
    vb:text {
      id = "my_text", 
      text = "Do what you see"
    },
    vb:button {
      text = "Hit Me!",
      tooltip = "Hit this button to change the text above.",
      notifier = function()
        local my_text_view = vb.views.my_text
        my_text_view.text = "Button was hit."
      end
    }
  }
}

renoise.app():show_custom_prompt(
  dialog_title, dialog_content, dialog_buttons)

```

--------------------------------

### Define and Use a DocumentList for Preferences

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Document.DocumentList.html

Demonstrates how to define a custom document type with a DocumentList, instantiate it, and populate it with entries. This is useful for managing tool preferences or any ordered collection of data.

```lua
-- define a class model for our complex type for document items in the list
-- so that Renoise knows how to load it later our entries will have
renoise.Document.create("Entry") {
  name = renoise.Document.ObservableString(),
  path = renoise.Document.ObservableString(),
}

-- create new entry instances with the given data
function create_entry(name, path)
  local entry = renoise.Document.instantiate("Entry")
  entry.name.value = name
  entry.path.value = path
  return entry
end

-- define a class model for our preferences which is using a list of entries
renoise.Document.create("MyPreferences") {
  list = renoise.Document.DocumentList()
}

-- assign a fresh instance of our main document as preferences
local preferences = renoise.Document.instantiate("MyPreferences")
renoise.tool().preferences = preferences

-- insert elements into the list using :insert(index, element)
-- we call our helper to create an instance of Entry
preferences.list:insert(1, create_entry("some name", "some/path"))

-- access entries by using :property(index)
print(preferences.list:property(1).name)

-- get the size of the list (you can use :size() as well)
print(#preferences.list)

-- loop over the list to print all entries
for i = 1, #preferences.list do
  local entry = preferences.list:property(i)
  print(i)
  print(entry.name)
  print(entry.path)
end

-- try reloading your tool to see the list get bigger

```

--------------------------------

### stmt:bind_parameter_count()

Source: https://renoise.github.io/xrnx/API/renoise/renoise.SQLite.html

Gets the largest statement parameter index in the prepared statement.

```APIDOC
## stmt:bind_parameter_count()

### Description
Gets the largest statement parameter index in prepared statement stmt. When the statement parameters are of the forms ":AAA" or "?", then they are assigned sequentially increasing numbers beginning with one, so the value returned is the number of parameters. However if the same statement parameter name is used multiple times, each occurrence is given the same number, so the value returned is the number of unique statement parameter names.
If statement parameters of the form "?NNN" are used (where NNN is an integer) then there might be gaps in the numbering and the value returned by this interface is the index of the statement parameter with the largest index value.

### Method
`stmt:bind_parameter_count() -> integer`
```

--------------------------------

### Create UDP Server and Echo Messages

Source: https://renoise.github.io/xrnx/guide/sockets.html

Creates a UDP server that listens on localhost and a specified port. It runs a loop that accepts incoming connections, logs client information, and echoes received messages back to the client. The server remains active as long as the script is running.

```lua
local server, socket_error = renoise.Socket.create_server(
  "localhost", 1025, renoise.Socket.PROTOCOL_UDP)
   
if socket_error then 
  renoise.app():show_warning(
     "Failed to start the echo server: " .. socket_error)
else
  server:run {
    ---@param socket_error string
    socket_error = function(socket_error)
      renoise.app():show_warning(socket_error)
    end,
    
    ---@param socket renoise.Socket.SocketClient
    socket_accepted = function(socket)
      print(("client %s:%d connected"):format(
        socket.peer_address, socket.peer_port))
    end,
  
    ---@param socket renoise.Socket.SocketClient
    ---@param message string
    socket_message = function(socket, message)
      print(("client %s:%d sent '%s'"):format(
        socket.peer_address, socket.peer_port,  message))
      -- Simply send the message back      
      socket:send(message)
    end    
  }
end
-- This server will run and echo messages as long as the script is active.

```

--------------------------------

### Create TCP Client and Send HTTP GET Request

Source: https://renoise.github.io/xrnx/guide/sockets.html

Creates a TCP client socket, connects to a web server, and sends an HTTP GET request. Handles connection timeouts and receives data until the server disconnects or a timeout occurs. Note that robust HTTP handling requires parsing headers.

```lua
local connection_timeout = 2000

local client, socket_error = renoise.Socket.create_client(
  "www.renoise.com", 80, renoise.Socket.PROTOCOL_TCP, connection_timeout)
   
if socket_error then 
  renoise.app():show_warning(socket_error)
  return
end

-- Request the root document
local succeeded, socket_error = 
  client:send("GET / HTTP/1.0\r\nHost: www.renoise.com\r\n\r\n")

if (socket_error) then 
  renoise.app():show_warning(socket_error)
  return
end

-- Loop until we get no more data from the server.
-- Note: A robust implementation should parse the HTTP header
-- and use the "Content-Length" to determine when to stop.
local receive_succeeded = false
local receive_content = ""

while (true) do
  -- Timeout for receiving data is 500ms
  local receive_timeout = 500
  
  local message, socket_error = 
    client:receive("*line", receive_timeout)
    
  if (message) then 
    receive_content = receive_content .. message .. "\n"
  else
    if (socket_error == "timeout" or 
        socket_error == "disconnected") 
    then
      -- Could retry on timeout, but we'll just stop in this example.
      receive_succeeded = true
      break
    else
      renoise.app():show_warning(
        "'socket receive' failed with the error: " .. socket_error)
      break
    end
  end
end
  
-- Close the connection if it was not already closed by the server
if (client and client.is_open) then
  client:close()
end

-- Show what we've got
if (receive_succeeded and #receive_content > 0) then
  renoise.app():show_prompt(
    "HTTP GET Response", 
    receive_content, 
    {"OK"}
  )
else
  renoise.app():show_prompt(
    "HTTP GET Response", 
    "Socket receive timeout or no content.", 
    {"OK"} 
  )
end

```

--------------------------------

### Create a clickable text link with URL action

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Views.TextLink.html

Demonstrates how to create a TextLink that opens a URL when clicked. Attach a notifier function to the TextLink to handle the click event and use `renoise.app():open_url()` to open the specified URL.

```Lua
local my_link = renoise.Views.TextLink.new()
my_link.text = "Click me!"
my_link:add_pressed_notifier(function ()
  renoise.app():open_url("https://renoise.com")
end)
-- Add my_link to a container view...
```

--------------------------------

### set_fill_linear_gradient

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Views.Canvas.Context.html

Sets the filling to use a linear gradient defined by start and end points.

```APIDOC
## set_fill_linear_gradient

### Description
Set filling to use a linear gradient. Positions the start and end points of the gradient and clears all color stops to reset the gradient to transparent black. Color stops can then be added again. When drawing, pixels will be painted with the color of the gradient at the nearest point on the line segment between the start and end points. This is affected by the current transform at the time of drawing.

### Method
Implicit (called on the context object)

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
- **start_x** (number) - Required - The x-coordinate of the gradient's start point.
- **start_y** (number) - Required - The y-coordinate of the gradient's start point.
- **end_x** (number) - Required - The x-coordinate of the gradient's end point.
- **end_y** (number) - Required - The y-coordinate of the gradient's end point.
```

--------------------------------

### Create Sample Data

Source: https://renoise.github.io/xrnx/API/renoise/renoise.SampleBuffer.html

Initializes a new sample data buffer with specified audio parameters. This function will overwrite any existing sample data. It returns true on success and false if memory allocation fails.

```Lua
create_sample_data(self, sample_rate : integer, bit_depth : integer, num_channels : integer, num_frames : integer)
->success : boolean
```

--------------------------------

### close_path

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Views.Canvas.Context.html

Closes the current subpath by drawing a straight line from the end to the start point.

```APIDOC
## close_path

### Description
Closes the current subpath. Adds a straight line from the end of the current subpath back to its first point and marks the subpath as closed. A new, empty subpath will be started beginning with the same first point. If the current path is empty, this does nothing.

### Method
Implicit (called on the context object)

### Endpoint
N/A (SDK method)

### Parameters
None
```

--------------------------------

### Dash Offset

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Views.Canvas.Context.html

Sets the offset for the dash pattern at the start of each subpath. Defaults to 0.0.

```APIDOC
## Dash Offset (`number`)

### Description
Offset where each subpath starts the dash pattern.

Changing this shifts the location of the dashes along the path and animating it will produce a marching ants effect. Only affects stroking and only when a dash pattern is set. May be negative or exceed the length of the dash pattern, in which case it will wrap. Defaults to 0.0.
```

--------------------------------

### Create a UDP OSC Server in Renoise

Source: https://renoise.github.io/xrnx/guide/osc.html

Use this snippet to set up a UDP server that listens for incoming OSC messages on a specified port. It handles message decoding and sends a reply back to the client.

```lua
-- Create some shortcuts
local OscMessage = renoise.Osc.Message
local OscBundle = renoise.Osc.Bundle

-- Open a socket connection to listen for messages
local server, socket_error = renoise.Socket.create_server(
  "localhost", 8008, renoise.Socket.PROTOCOL_UDP)
   
if (socket_error) then 
  renoise.app():show_warning(("Failed to start the " .. 
    "OSC server. Error: '%s'"):format(socket_error))
  return
end

server:run {
  socket_message = function(socket, data) 
    -- Decode the binary data to an OSC message or bundle
    local message_or_bundle, osc_error = renoise.Osc.from_binary_data(data)
    
    -- Show what we've got
    if (message_or_bundle) then
      if (type(message_or_bundle) == "Message") then
        print(("Got OSC message: '%s'"):format(tostring(message_or_bundle)))

      elseif (type(message_or_bundle) == "Bundle") then
        print(("Got OSC bundle: '%s'"):format(tostring(message_or_bundle)))
      end
      
      -- Send a reply back to the client
      local reply_message = OscMessage("/renoise/reply", {
        { tag = "s", value = "Thank you for the message!" }
      })
      socket:send(reply_message:to_binary_data())
      
    else
      print(("Got invalid OSC data, or data which is not " .. 
        "OSC data at all. Error: '%s'"):format(osc_error))
    end
  end    
}

-- To shut down the server at any time, call:
-- server:close()

```

--------------------------------

### Instantiate Document by Model Name

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Document.html

Shows how to create a new instance of a document model that has been previously registered using renoise.Document.create.

```lua
-- create a new instance of "MyDoc"
my_other_document = renoise.Document.instantiate("MyDoc")
```

--------------------------------

### table.find

Source: https://renoise.github.io/xrnx/API/modules/table.html

Finds the first occurrence of a value in a table, optionally starting from a specified index.

```APIDOC
## table.find

### Description
Find the first match of _value_ in the given table, starting from element number _start_index_. Returns the first _key_ that matches the value or nil.

### Parameters
* **t** (`table`) - Required - The table to search within.
* **value** (`any`) - Required - The value to search for.
* **start_index** (`integer`?) - Optional - The index to start searching from.

### Return Value
* `string` | `number`? - The key of the first matching value, or nil if not found.

### Examples
```lua
t = {"a", "b"}; table.find(t, "a") -- Output: 1
t = {a=1, b=2}; table.find(t, 2) -- Output: "b"
t = {"a", "b", "a"}; table.find(t, "a", 2) -- Output: "3"
t = {"a", "b"}; table.find(t, "c") -- Output: nil
```
```

--------------------------------

### Instantiating Documents by Model Name

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Document.html

Explains how to create new instances of previously defined document models using `renoise.Document.instantiate`.

```APIDOC
## renoise.Document.instantiate(model_name : string)

### Description
Creates a new instance of the given document model. The `model_name` must have been registered with `renoise.Document.create` beforehand.

### Parameters
#### Path Parameters
- **model_name** (string) - Required - The name of the document model to instantiate.

### Request Example
```lua
-- create a new instance of "MyDoc"
my_other_document = renoise.Document.instantiate("MyDoc")
```
```

--------------------------------

### Canvas View Example

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Views.Canvas.html

A visual representation of a canvas, possibly for ASCII art or simple graphics.

```text
.--.
.'_/_'.
'. /\ .'
  "||"
   || /\
/\ ||//\
(/\\||/
______\||
_______
```

--------------------------------

### Access Sample Device Chain by Index

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Instrument.html

Accesses a single sample device chain by its index. Use 'sample_device_chains' to iterate.

```APIDOC
## sample_device_chain

### Description
Access to a single device chain by index. Use property 'sample_device_chains' to iterate over all chains and to query the chain count.

### Method
`renoise.Instrument` (implicit)

### Parameters
- **index** (`integer`) - The index of the device chain to access.
```

--------------------------------

### Instantiate a Custom Document Object

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Document.html

Demonstrates how to create an instance of a custom document class after it has been defined.

```lua
my_document = MyDocument()
-- do something with my_document, load/save, add/remove more properties
```

--------------------------------

### Getting the Current Value of a View

Source: https://renoise.github.io/xrnx/API/renoise/renoise.ViewBuilder.html

Retrieves the current numerical value of the view. This property is read-only.

```lua
number
-- The current value of the view
```

--------------------------------

### Get High Precision Timer

Source: https://renoise.github.io/xrnx/API/modules/os.html

Replaced with a high precision timer, still expressed in milliseconds.

```lua
return clock()
```

--------------------------------

### Creating and Modifying Documents

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Document.html

Demonstrates how to create a new document, add and remove properties, and nest documents.

```APIDOC
## renoise.Document.create(model_name : string)

### Description
Creates an empty document node or a document node modeled after the passed key-value table. The `model_name` is used to identify the document's type when loading/saving and allows for instantiation of new document objects.

### Parameters
#### Path Parameters
- **model_name** (string) - Required - The name to identify the document type.

### Request Example
```lua
-- Creates an empty document, using "MyDoc" as the model name (a type name)
local my_document = renoise.Document.create("MyDoc") { }
-- adds a number to the document with the initial value 1
my_document:add_property("value1", 1)
-- adds a string
my_document:add_property("value2", "bla")
-- create another document and adds it
local node = renoise.Document.create("MySubDoc") { }
node:add_property("another_value", 1)
-- add another already existing node
my_document:add_property("nested_node", node)
-- removes a previously added node
my_document:remove_property(node)
-- access properties
local value1 = my_document.value1
value1 = my_document:property("value1")
```
```

--------------------------------

### Advanced Document Creation with Properties

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Document.html

Demonstrates creating a document node with initial properties, including explicit type definitions and nested structures.

```APIDOC
## renoise.Document.create with properties

### Description
Creates a document node modeled after a passed table, allowing for initial property values and explicit type definitions. The model name is used for identification during loading/saving and for creating new instances.

### Parameters
#### Path Parameters
- **model_name** (string) - Required - The name to identify the document type.
- **properties** (ObservableProperties) - Optional - A table of properties to initialize the document with.

### Request Example
```lua
my_document = renoise.Document.create("MyDoc") {
  age = 1,
  name = "bla", -- implicitly specify a property type
  is_valid = renoise.Document.ObservableBoolean(false), -- or explicitly
  age_list = {1, 2, 3},
  another_list = renoise.Document.ObservableNumberList(),
  sub_node = {
    sub_value1 = 2,
    sub_value2 = "bla2"
  }
}
```

### Notes
- The passed table is used only during construction to determine property types. Subsequent modifications do not affect the model.
- Explicitly specify types using `renoise.Document.ObservableXXX()` or ensure values are provided to infer types.
- The `model_name` is crucial for loading/saving consistency and for using `renoise.Document.instantiate`.
```

--------------------------------

### Get Selected Text from MultiLineTextField

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Views.MultiLineTextField.html

Retrieves the currently selected text. Newlines are normalized to the Unix format.

```lua
selected_text : string
```

--------------------------------

### SampleAhdrsModulationDevice Functions

Source: https://renoise.github.io/xrnx/API/renoise/renoise.SampleAhdrsModulationDevice.html

Provides functions for initializing, copying, and accessing parameters of the SampleAhdrsModulationDevice.

```APIDOC
## Functions

*   **init(self)**: Reset the device to its default state.
*   **copy_from(self, other_device : `renoise.SampleModulationDevice`)**: Copy a device's state from another device. 'other_device' must be of the same type.
*   **parameter(self, index : `integer`) -> `renoise.DeviceParameter`**: Access to a single parameter by index. Use properties 'parameters' to iterate over all parameters and to query the parameter count.
```

--------------------------------

### Application Window Properties

Source: https://renoise.github.io/xrnx/API/renoise/renoise.ApplicationWindow.html

These properties allow you to get and set various states of the Renoise application window.

```APIDOC
## Properties

### `fullscreen` : `boolean`
Get/set if the application is running fullscreen.

### `is_maximized` : `boolean`
**READ-ONLY**. Window status flag.

### `is_minimized` : `boolean`
**READ-ONLY**. Window status flag.

### `lock_keyboard_focus` : `boolean`
Get/set if keyboard focus is locked.

### `sample_record_dialog_is_visible` : `boolean`
Get/set if the sample record dialog is visible.

### `disk_browser_is_visible` : `boolean`
Get/set if the disk browser is visible.

### `disk_browser_category` : `renoise.ApplicationWindow.DiskBrowserCategory`
Get/set the current category of the disk browser.

### `instrument_box_is_visible` : `boolean`
Get/set if the instrument box is visible.

### `instrument_box_slot_size` : `renoise.ApplicationWindow.InstrumentBoxSlotSize`
Get/set the slot size of the instrument box.

### `instrument_editor_is_detached` : `boolean`
Get/set if the instrument editor is detached.

### `instrument_properties_is_visible` : `boolean`
Get/set if the instrument properties panel is visible.

### `instrument_properties_show_volume_transpose` : `boolean`
Get/set if volume and transpose are shown in instrument properties.

### `instrument_properties_show_trigger_options` : `boolean`
Get/set if trigger options are shown in instrument properties.

### `instrument_properties_show_scale_options` : `boolean`
Get/set if scale options are shown in instrument properties.

### `instrument_properties_show_plugin` : `boolean`
Get/set if plugin information is shown in instrument properties.

### `instrument_properties_show_plugin_program` : `boolean`
Get/set if plugin program information is shown in instrument properties.

### `instrument_properties_show_midi` : `boolean`
Get/set if MIDI information is shown in instrument properties.

### `instrument_properties_show_midi_program` : `boolean`
Get/set if MIDI program information is shown in instrument properties.

### `instrument_properties_show_macros` : `boolean`
Get/set if macros are shown in instrument properties.

### `instrument_properties_show_phrases` : `boolean`
Get/set if phrases are shown in instrument properties.

### `sample_properties_is_visible` : `boolean`
Get/set if the sample properties panel is visible.

### `mixer_view_is_detached` : `boolean`
Get/set if the mixer view is detached.

### `upper_frame_is_visible` : `boolean`
Get/set if the upper frame is visible.

### `active_upper_frame` : `renoise.ApplicationWindow.UpperFrame`
Get/set the active upper frame.

### `active_middle_frame` : `renoise.ApplicationWindow.MiddleFrame`
Get/set the active middle frame.

### `lower_frame_is_visible` : `boolean`
Get/set if the lower frame is visible.

### `active_lower_frame` : `renoise.ApplicationWindow.LowerFrame`
Get/set the active lower frame.

### `right_frame_is_visible` : `boolean`
Get/set if the right frame is visible.

### `pattern_matrix_is_visible` : `boolean`
Get/set if the pattern matrix is visible.

### `pattern_advanced_edit_is_visible` : `boolean`
Get/set if the advanced pattern edit mode is visible.

### `mixer_view_post_fx` : `boolean`
Get/set if post-FX are visible in the mixer.

### `mixer_fader_type` : `renoise.ApplicationWindow.MixerFader`
Get/set the type of faders in the mixer view.
```

--------------------------------

### Insert Sample Device Chain

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Instrument.html

Inserts a new sample device chain at the specified index.

```APIDOC
## insert_sample_device_chain

### Description
Insert a new sample device chain at the given index.

### Method
`renoise.Instrument` (implicit)

### Parameters
- **index** (`integer`) - The index at which to insert the new device chain.
```

--------------------------------

### Reverse Table Iteration with ripairs

Source: https://renoise.github.io/xrnx/API/modules/global.html

Iterate over a table in reverse order. Useful for processing elements from end to start.

```Lua
t = {"a", "b", "c"}
for k,v in ripairs(t) do print(k, v) end -> "3 c, 2 b, 1 a"
```

--------------------------------

### active_clipboard_index

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Application.html

Get or set globally used clipboard "slots" in the application. Range: (1 - 4).

```APIDOC
## active_clipboard_index

### Description
Get or set globally used clipboard "slots" in the application.

### Type
`1` | `2` | `3` | `4`

### Range
(1 - 4)
```

--------------------------------

### Open and Read from SQLite Database in Renoise

Source: https://renoise.github.io/xrnx/guide/sqlite.html

Demonstrates opening an existing SQLite database in read-only mode and querying data using prepared statements. Ensure the database file exists before opening.

```lua
-- create a new database (rwc = read/write/create)
local db, status, error = renoise.SQLite.open("./some_test.db", "rwc")
-- NB: use renoise.SQLite.open() to create a in-memory db instead
print("Create:", db.is_open, db.error_code, db.error_message)

local sql = [[
  CREATE TABLE numbers(num1,num2,str);
  INSERT INTO numbers VALUES(1,11,"ABC");
  INSERT INTO numbers VALUES(2,22,"DEF");
  INSERT INTO numbers VALUES(3,33,"UVW");
  INSERT INTO numbers VALUES(4,44,"XYZ");
]]

print("Exec:", db:execute(sql))
print("Changes:", db.changes, db.total_changes, db.error_message)

-- read from an existing db using a prepared statement
local db, status, error = renoise.SQLite.open("./test.db", "ro") -- read-only
print("Open:", db.is_open, db.error_code, db.error_message)

local stm = db:prepare("SELECT * from numbers")
print("Read:", stm.columns, stm.unames)

for k in stm:rows() do
 rprint(k) 
end

```

--------------------------------

### Load, Save, and Handle New Documents

Source: https://renoise.github.io/xrnx/guide/application.html

Manage song files by loading, saving, and setting up notifiers to execute code after a new document is created or loaded.

```lua
local app = renoise.app()

-- This will show a file dialog to the user. The song is not loaded immediately.
app:load_song("/path/to/some/song_file") 

-- To run code after a new song is ready, use a notifier.
-- This is typically done in your tool's initialization code.
function handle_new_document()
  print("A new song was created or loaded. The new song name is: " ..
    renoise.song().name)
end

-- The 'new_document_observable' is fired after a new song is
--- successfully created or loaded.
renoise.tool().app_new_document_observable:add_notifier(handle_new_document)

-- To save a song to a specific file:
app:save_song_as("/path/to/MyNewSong.xrns")
```

--------------------------------

### add_rect

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Views.Canvas.Context.html

Adds a closed subpath in the shape of a rectangle to the canvas context. The rectangle is defined by a starting point and its width and height.

```APIDOC
## add_rect

### Description
Add a closed subpath in the shape of a rectangle.

The rectangle has one corner at the given point and then goes in the direction along the width before going in the direction of the height towards the opposite corner. The current transform at the time that this is called will affect the given point and rectangle. The width and/or the height may be negative or zero, and this can affect the winding direction.

### Parameters
#### Path Parameters
- **_self** (object) - Required - The canvas context object.
- **x** (number) - Required - The x-coordinate of the rectangle's starting corner.
- **y** (number) - Required - The y-coordinate of the rectangle's starting corner.
- **width** (number) - Required - The width of the rectangle.
- **height** (number) - Required - The height of the rectangle.
```

--------------------------------

### Select Pattern Lines

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Song.html

Select a range of lines within the pattern editor. This example selects lines 1 to 4.

```Lua
renoise.song().selection_in_pattern = { start_line = 1, end_line = 4 }
```

--------------------------------

### Sample Manipulation

Source: https://renoise.github.io/xrnx/API/renoise/renoise.Sample.html

Methods for managing sample data and settings.

```APIDOC
## reset()

### Description
Resets the sample, clearing all sample settings and sample data.

### Method
`renoise.Sample.reset`
```

```APIDOC
## copy(sample)

### Description
Copies all settings, including sample data, from another sample.

### Method
`renoise.Sample.copy`

### Parameters
- **sample** (`renoise.Sample`) - The sample to copy from.
```

--------------------------------

### Create MIDI Input Device and Handle Messages

Source: https://renoise.github.io/xrnx/guide/midi.html

Creates an input MIDI device and registers a callback for incoming MIDI messages. Ensure the device variable is kept alive (e.g., global) to prevent it from closing automatically.

```lua
-- NOTE: The MIDI device will be closed when this local variable gets garbage
-- collected. Make it global or assign it to a table that is held globally
-- to keep it active.
local midi_device = nil

local inputs = renoise.Midi.available_input_devices()
if not table.is_empty(inputs) then
  -- Use the first available device in this example
  local device_name = inputs[1]
  
  local function midi_callback(message)
    assert(#message == 3)
    assert(message[1] >= 0 and message[1] <= 0xff)
    assert(message[2] >= 0 and message[2] <= 0xff)    
    assert(message[3] >= 0 and message[3] <= 0xff)
    
    print(('%s: got MIDI %X %X %X'):format(device_name, 
      message[1], message[2], message[3]))
  end

  -- The sysex callback is an optional second argument.
  midi_device = renoise.Midi.create_input_device(
    device_name, midi_callback)
  
  -- To stop listening, call: midi_device:close()
end

```

--------------------------------

### TextAlignment

Source: https://renoise.github.io/xrnx/API/renoise/renoise.ViewBuilder.html

Setup the text's alignment. Applies only when the view's size is larger than the needed size to draw the text.

```APIDOC
## TextAlignment

### Description
Setup the text's alignment. Applies only when the view's size is larger than the needed size to draw the text.

### Parameters
#### Path Parameters
- **alignment** (string) - Required - The alignment of the text. Can be one of: "left", "right", or "center".

### Example
```lua
-- Align text to the center
view.TextAlignment = "center"
```
```
Tokens:
Raw