Skip to main content

core.audioview

A streaming audio player with a recursive playlist and optional visualization.

local audioview = require "core.audioview"

NEWLINE​

(field) NEWLINE: integer

Indicates on a widget.styledtext that a new line follows.

__index​

(field) __index: core.object

Base class providing OOP functionality for Lua. All classes in Pragtical inherit from Object.

analysis​

(field) analysis: table

animations​

(field) animations: widget.animation[]

background_color​

(field) background_color: renderer.color

Array of bytes that represents a color used by the rendering functions.

border​

(field) border: widget.border

Represents the border of a widget.

captured_widget​

(field) captured_widget: widget

Widget that captured mouse events

child_active​

(field) child_active: widget|nil

A base widget

childs​

(field) childs: table<integer, widget>

clickable​

(field) clickable: boolean

closed​

(field) closed: boolean

context​

(field) context: 'application'|'session'

controls​

(field) controls: table

current​

(field) current: any

current_scale​

(field) current_scale: number

cursor​

(field) cursor: 'arrow'|'hand'|'ibeam'|'sizeh'|'sizev'

defer_draw​

(field) defer_draw: boolean

draggable​

(field) draggable: boolean

dragged​

(field) dragged: boolean

duration​

(field) duration: number?

error​

(field) error: string

explicit_update​

(field) explicit_update: boolean

filter​

(field) filter: widget.textbox

filter_due​

(field) filter_due: number

folder​

(field) folder: widget.filepicker

font​

(field) font: string|renderer.font|widget.fontreference

Represents a reference to a font stored elsewhere.

force_events​

(field) force_events: table

foreground_color​

(field) foreground_color: renderer.color

Array of bytes that represents a color used by the rendering functions.

generation​

(field) generation: integer

graph_h​

(field) graph_h: number

graph_y​

(field) graph_y: number

h_scrollbar​

(field) h_scrollbar: widget.scrollbar

has_focus​

(field) has_focus: boolean

hovered_scrollbar​

(field) hovered_scrollbar: boolean

input_text​

(field) input_text: boolean

is_scrolling​

(field) is_scrolling: boolean

label​

(field) label: string|table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>

list​

(field) list: widget.listbox

list_height​

(field) list_height: number

list_row_count​

(field) list_row_count: integer

list_width​

(field) list_width: integer

mixer​

(field) mixer: audio.mixer

Independent device-backed or offline playback owner. Initially unpaused with gain 1 and rate 1. Groups and voices use the same operations in either mode.

mouse​

(field) mouse: widget.position

Represents the position of a widget.

mouse_is_hovering​

(field) mouse_is_hovering: boolean

mouse_is_pressed​

(field) mouse_is_pressed: boolean

mouse_pressed_outside​

(field) mouse_pressed_outside: boolean

name​

(field) name: string

next​

(field) next: widget.button

next_zindex​

(field) next_zindex: integer

parent​

(field) parent: widget|nil

A base widget

perform_update_size_position​

(field) perform_update_size_position: boolean

play_button​

(field) play_button: widget.button

position​

(field) position: widget.position

Represents the position of a widget.

position_seconds​

(field) position_seconds: number

prev_height​

(field) prev_height: number?

prev_size​

(field) prev_size: widget.position

Represents the position of a widget.

prev_view​

(field) prev_view: unknown

prev_width​

(field) prev_width: number?

previous​

(field) previous: widget.button

render_background​

(field) render_background: boolean

repeat_all​

(field) repeat_all: any

repeat_button​

(field) repeat_button: widget.togglebutton

resume_position​

(field) resume_position: unknown

scan_skipped​

(field) scan_skipped: integer

scanning​

(field) scanning: boolean

scroll​

(field) scroll: core.view.scroll

scrollable​

(field) scrollable: boolean

seek​

(field) seek: core.object

Base class providing OOP functionality for Lua. All classes in Pragtical inherit from Object.

set_focus​

(field) set_focus: any

shuffle​

(field) shuffle: any

shuffle_button​

(field) shuffle_button: widget.togglebutton

shuffle_history​

(field) shuffle_history: table

shuffle_index​

(field) shuffle_index: any

shuffle_remaining​

(field) shuffle_remaining: table

size​

(field) size: widget.position

Modifying this property directly is not advised, use set_size() instead.

skip_scroll_ctrl​

(field) skip_scroll_ctrl: boolean

By default is set to true to allow ctrl+wheel or cmd+wheel on mac to scale the interface, you can set it to false on your parent widget to allow manually intercepting ctrl+wheel.

state​

(field) state: string|"finished"|"paused"|"playing"|"stopped"

stop_after_track​

(field) stop_after_track: boolean

stop_button​

(field) stop_button: widget.button

super​

(field) super: widget

A base widget

textview​

(field) textview: widget

A base widget

time_y​

(field) time_y: number

title_y​

(field) title_y: number

tooltip​

(field) tooltip: (string|table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>)?

tooltip_command​

(field) tooltip_command: string?

tracks​

(field) tracks: table

tracks_by_path​

(field) tracks_by_path: table

type_name​

(field) type_name: string

updated​

(field) updated: boolean

v_scrollbar​

(field) v_scrollbar: widget.scrollbar

visible​

(field) visible: boolean

visualization​

(field) visualization: any

visualization_button​

(field) visualization_button: widget.togglebutton

voice​

(field) voice: audio.voice

One loaded-sound, file, or generated-stream playback instance. A finished/stopped voice cannot restart; request a new voice. Status remains readable after it ends.

volume​

(field) volume: any

volume_slider​

(field) volume_slider: core.object

Base class providing OOP functionality for Lua. All classes in Pragtical inherit from Object.

zindex​

(field) zindex: integer

from_state​

function core.audioview.from_state(state: table)
  -> core.audioview

Restore a player without scanning directories or starting audio playback.

@return: core.audioview

is_supported​

function core.audioview.is_supported(path: string)
  -> supported: boolean
  2. extension: string?

Check whether a filename's extension has an available decoder.

@return supported: boolean

@return extension: string?

override_rootview​

function widget.override_rootview()

Called when initializing a floating widget to generate RootView overrides, this function will only override the events once.

__call​

(method) core.object:__call(...any)
  -> obj: core.object

Metamethod allowing class to be called like a constructor. Enables syntax: local obj = MyClass(args) instead of MyClass:new(args) Automatically creates instance and calls new() with provided arguments.

@return obj: core.object — The new instance of the class

__tostring​

(method) core.audioview:__tostring()
  -> string

activate​

(method) widget:activate()

Emitted to input_text widgets when clicked.

add_child​

(method) widget:add_child(child: widget)

Add a child widget, automatically assign a zindex if non set and sorts them in reverse order for better events matching.

@param child: widget — A base widget

add_row​

(method) core.audioview:add_row(track: any)

add_track​

(method) core.audioview:add_track(track: any)
  -> unknown

advance​

(method) core.audioview:advance(direction: any, automatic: any)

animate​

(method) widget:animate(target?: table, properties: table<string, number>, options?: widget.animation.options)

Registers a new animation to be ran on the update cycle.

@param target?: table — If nil assumes properties belong to widget it self.

@param options?: widget.animation.options

capture_mouse​

(method) widget:capture_mouse(scrolling?: boolean)

All mouse events will be directly sent to the widget even if mouse moves outside the widget region.

@param scrolling?: boolean — Capture for scrolling

centered​

(method) widget:centered()

Center the widget horizontally and vertically to the screen or parent widget.

clamp_scroll_position​

(method) core.view:clamp_scroll_position()

Clamp scroll position to valid range (0 to max scrollable size). Called automatically by update(). Override get_scrollable_size() to customize.

deactivate​

(method) widget:deactivate()

Emitted to input_text widgets on lost focus.

destroy​

(method) widget:destroy()

If floating, remove the widget from the floating widgets list to allow proper garbage collection.

destroy_childs​

(method) widget:destroy_childs()

Recursively destroy all childs from the widget.

drag​

(method) widget:drag(x: number, y: number)

Used internally when dragging is activated.

draw​

(method) core.audioview:draw()

draw_background​

(method) core.view:draw_background(color: renderer.color)

Draw a solid background color for the entire view. Commonly called at the start of draw() methods.

@param color: renderer.color — Array of bytes that represents a color used by the rendering functions.

draw_border​

(method) widget:draw_border(x?: number, y?: number, w?: number, h?: number)

Draw the widget configured border or custom one.

draw_scrollbar​

(method) widget:draw_scrollbar()

draw_styled_text​

(method) widget:draw_styled_text(text: table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>, x: integer, y: integer, only_calc?: boolean, start_idx?: integer, end_idx?: integer)
  -> width: integer
  2. height: integer

Render or calculate the size of the specified range of elements in a styled text elemet.

@param text: table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>

@return width: integer

@return height: integer

draw_text_multiline​

(method) widget:draw_text_multiline(font: string|renderer.font|widget.fontreference, text: string, x: integer, y: integer, color: renderer.color, only_calc: boolean)
  -> resx: integer
  2. resy: integer
  3. width: integer
  4. height: integer

Taken from the logview and modified it a tiny bit. TODO: something similar should be on pragtical core.

@param font: string|renderer.font|widget.fontreference — Represents a reference to a font stored elsewhere.

@param color: renderer.color — Array of bytes that represents a color used by the rendering functions.

@return resx: integer

@return resy: integer

@return width: integer

@return height: integer

extend​

(method) core.object:extend()
  -> cls: core.object

Create a new class that inherits from this one. Returns a new class with this class as its parent. Example: local MyClass = Object:extend()

@return cls: core.object — The new class table

extends​

(method) core.object:extends(T: any)
  -> extends: boolean

Check if object inherits from the given type (inheritance-aware). Use this to check class hierarchy. Example: view:extends(View) returns true for View and all subclasses

@param T: any — Class to check inheritance from

@return extends: boolean — True if object is T or inherits from T

filter_tracks​

(method) core.audioview:filter_tracks()

force_event​

(method) widget:force_event(name: "mouse_released", force: boolean)

Toggle the forced interception of given event even if all the conditions for emitting it are not met.

Note: only "mouse_released" is implemented for the moment on floating views for use in the SelectBox, maybe a better system can be implemented on the future.

name:
    | "mouse_released"

@param force: boolean — If omitted is set to true by default

get_bottom​

(method) widget:get_bottom()
  -> number

Get the bottom y coordinate relative to parent

get_content_bounds​

(method) core.view:get_content_bounds()
  -> x1: number
  2. y1: number
  3. x2: number
  4. y2: number

Get the content bounds in content coordinates (accounting for scroll).

@return x1: number — Left edge

@return y1: number — Top edge

@return x2: number — Right edge

@return y2: number — Bottom edge

get_content_offset​

(method) core.view:get_content_offset()
  -> x: number
  2. y: number

Get the top-left corner of content area in screen coordinates. Accounts for scroll offset. Use for drawing content at correct position.

@return x: number — Screen x coordinate

@return y: number — Screen y coordinate

get_font​

(method) widget:get_font(font?: string|renderer.font|widget.fontreference)
  -> renderer.font

Get the real renderer.font associated with a widget.font.

@param font?: string|renderer.font|widget.fontreference — Represents a reference to a font stored elsewhere.

@return: renderer.font

get_h_scrollable_size​

(method) widget:get_h_scrollable_size()
  -> number

Calculates the x scrollable size taking into account the right most widget or the size of the widget it self if greater.

get_height​

(method) widget:get_height()
  -> number

Get height including borders.

get_module​

(method) core.view:get_module()
  -> path: string?

Returns the module path of this view.

This method resolves the Lua module name that loaded the concrete view class (for example "core.view").

If the view class cannot be associated with any loaded module, nil is returned.

@return path: string?

get_name​

(method) widget:get_name()
  -> string

The name that is displayed on pragtical tabs.

get_position​

(method) widget:get_position()
  -> widget.position

Get the relative position in relation to parent

@return: widget.position

get_real_height​

(method) widget:get_real_height()
  -> number

Overall height of the widget accounting all visible child widgets.

get_real_width​

(method) widget:get_real_width()
  -> number

Overall width of the widget accounting all visible child widgets.

get_right​

(method) widget:get_right()
  -> number

Get the right x coordinate relative to parent

get_scrollable_size​

(method) widget:get_scrollable_size()
  -> number

Calculates the y scrollable size taking into account the bottom most widget or the size of the widget it self if greater.

get_size​

(method) widget:get_size()
  -> widget.position

@return: widget.position

get_state​

(method) core.audioview:get_state()
  -> table

Return workspace state without retaining widgets or native audio handles.

get_width​

(method) widget:get_width()
  -> number

Get width including borders.

hide​

(method) widget:hide()

Hide the widget.

hide_animated​

(method) widget:hide_animated(lock_x?: boolean, lock_y?: boolean, options?: widget.animation.options)

Perform an animated hide.

@param lock_x?: boolean — Do not resize width while animating

@param lock_y?: boolean — Do not resize height while animating

@param options?: widget.animation.options

is​

(method) core.object:is(T: any)
  -> is_exact: boolean

Check if object is exactly of the given type (no inheritance check). Use this for strict type matching. Example: view:is(DocView) returns true only if view is a DocView, not a subclass

@param T: any — Class to check against

@return is_exact: boolean — True if object is exactly type T

is_class_of​

(method) core.object:is_class_of(T: any)
  -> is_instance: boolean

Check if the given object is exactly an instance of this class. Inverse of is() - checks if T is an instance of self. Example: DocView:is_class_of(obj) checks if obj is exactly a DocView

@param T: any — Object to check

@return is_instance: boolean — True if T is exactly an instance of this class

is_extended_by​

(method) core.object:is_extended_by(T: any)
  -> is_extended: boolean

Check if the given object/class inherits from this class. Inverse of extends() - checks if T is a subclass of self. Example: View:is_extended_by(DocView) checks if DocView inherits from View

@param T: any — Object or class to check

@return is_extended: boolean — True if T inherits from this class

is_visible​

(method) widget:is_visible()
  -> boolean

Check if the widget is visible also recursing to the parent visibility.

mouse_on_top​

(method) widget:mouse_on_top(x: number, y: number)
  -> boolean

Check if the given mouse coordinate is hovering the widget

move_towards​

(method) core.view:move_towards(t: table, k: string|number, dest: number, rate?: number, name?: string)

Smoothly animate a value towards a destination. Use this for animations instead of direct assignment.

@param t: table — Table containing the value

@param k: string|number — Key in table

@param dest: number — Target value

@param rate?: number — Animation speed (0-1, default 0.5, higher = faster)

@param name?: string — Transition name (for config.disabled_transitions)

new​

(method) core.audioview:new()

on_change​

(method) widget:on_change(value: any)

Event emitted when the value of the widget changes. If applicable, child widgets should call this method when its value changes.

on_click​

(method) widget:on_click(button: "left"|"right", x: number, y: number)

Click event emitted on a succesful on_mouse_pressed and on_mouse_released events combo.

button:
    | "left"
    | "right"

on_file_dropped​

(method) core.audioview:on_file_dropped(path: string)
  -> boolean

on_ime_text_editing​

(method) core.view:on_ime_text_editing(text: string, start: number, length: number)

Handle IME (Input Method Editor) text composition events. Override for IME support in text editors. Called during composition.

@param text: string — Composition text being edited

@param start: number — Start position of selection within composition

@param length: number — Length of selection within composition

on_mouse_enter​

(method) widget:on_mouse_enter(x: any, y: any, dx: any, dy: any)

Emitted once when the mouse hovers the widget.

on_mouse_leave​

(method) widget:on_mouse_leave(x: any, y: any, dx: any, dy: any)

Emitted once when the mouse leaves the widget.

on_mouse_left​

(method) widget:on_mouse_left()

on_mouse_moved​

(method) widget:on_mouse_moved(x: number, y: number, dx: number, dy: number)
  -> boolean

Besides the on_mouse_moved this event emits on_mouse_enter and on_mouse_leave for easy hover effects. Also, if the widget is scrollable and pressed this will drag it unless there is an active input_text child active.

on_mouse_pressed​

(method) widget:on_mouse_pressed(button: "left"|"right", x: number, y: number, clicks: integer)
  -> processed: boolean

Send mouse pressed events to hovered child or starts dragging if enabled.

button:
    | "left"
    | "right"

@return processed: boolean

on_mouse_released​

(method) widget:on_mouse_released(button: "left"|"right", x: number, y: number)
  -> processed: boolean

Send mouse released events to hovered child, ends dragging if enabled and emits on click events if applicable.

button:
    | "left"
    | "right"

@return processed: boolean

on_mouse_wheel​

(method) widget:on_mouse_wheel(y: number, x: number)
  -> boolean

on_scale_change​

(method) widget:on_scale_change(new_scale: number, prev_scale: number)

Can be overriden by widgets to listen for scale change events to apply any neccesary changes in sizes, padding, etc...

on_text_input​

(method) widget:on_text_input(text: string)
  -> processed: boolean

Redirects any text input to active child with the input_text flag.

@return processed: boolean

on_touch_moved​

(method) core.view:on_touch_moved(x: number, y: number, dx: number, dy: number, i: number)

Handle touch move events (touchscreen/trackpad gestures). Override for touch-specific behavior. Base implementation handles scrolling.

@param x: number — Current touch x coordinate

@param y: number — Current touch y coordinate

@param dx: number — Delta x since last position

@param dy: number — Delta y since last position

@param i: number — Touch finger/pointer index

open_file​

(method) core.audioview:open_file(path: string)

Play only this file, preserving playback when reopening the current track.

play​

(method) core.audioview:play(track: any, history_index: any)

play_selected​

(method) core.audioview:play_selected()

poll​

(method) core.audioview:poll()

release_mouse​

(method) widget:release_mouse()

Undo capture_mouse()

remove_child​

(method) widget:remove_child(child: widget)

Remove a child widget.

@param child: widget — A base widget

report​

(method) core.audioview:report(err: any)

reset_shuffle​

(method) core.audioview:reset_shuffle()

run_animations​

(method) widget:run_animations()

Runs all registered animations removing duplicated and finished ones.

scan​

(method) core.audioview:scan(path: any)

schedule_update​

(method) widget:schedule_update(delayed: any)

Schedule a core update and redraw. Since widgets try to not fire updates and draws to child widgets to reduce cpu consumption this function can be used when a re-update and re-draw is strictly needed.

scrollbar_dragging​

(method) core.view:scrollbar_dragging()
  -> dragging: boolean

Check if user is currently dragging either scrollbar.

@return dragging: boolean — True if scrollbar drag is in progress

scrollbar_hovering​

(method) core.view:scrollbar_hovering()
  -> hovering: boolean

Check if mouse is hovering over either scrollbar track.

@return hovering: boolean — True if mouse is over scrollbar

scrollbar_overlaps_point​

(method) core.view:scrollbar_overlaps_point(x: number, y: number)
  -> overlaps: boolean

Check if a screen point overlaps either scrollbar. Useful for determining cursor style or handling clicks.

@param x: number — Screen x coordinate

@param y: number — Screen y coordinate

@return overlaps: boolean — True if point is over vertical or horizontal scrollbar

seek_by​

(method) core.audioview:seek_by(seconds: any)

seek_to​

(method) core.audioview:seek_to(seconds: any)

select_row​

(method) core.audioview:select_row(direction: any)

set_border_width​

(method) widget:set_border_width(width: integer)

Set the widget border size and appropriately re-set the widget size.

set_label​

(method) widget:set_label(text: string|table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>)

A text label for the widget, not all widgets support this.

@param text: string|table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>

set_position​

(method) widget:set_position(x?: integer, y?: integer)

Set the position of the widget and updates the child absolute coordinates

set_size​

(method) widget:set_size(width?: integer, height?: integer)

set_target_size​

(method) widget:set_target_size(axis: string|'x'|'y', value: number)
  -> boolean

Called by pragtical node system to properly resize the widget.

axis:
    | 'x'
    | 'y'

set_tooltip​

(method) widget:set_tooltip(tooltip?: string|table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>, command?: string)

Text displayed when the widget is hovered. If a command name is also given its associated binding will be displayed as part of the tooltip.

@param tooltip?: string|table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>

set_visualization​

(method) core.audioview:set_visualization(enabled: any)

show​

(method) widget:show()

Show the widget.

show_animated​

(method) widget:show_animated(lock_x?: boolean, lock_y?: boolean, options?: widget.animation.options)

Perform an animated show.

@param lock_x?: boolean — Do not resize width while animating

@param lock_y?: boolean — Do not resize height while animating

@param options?: widget.animation.options

stop​

(method) core.audioview:stop()

supports_text_input​

(method) core.view:supports_text_input()
  -> boolean

Whether this view accepts text input (enables IME). Override and return true for text editors and input fields.

swap_active_child​

(method) widget:swap_active_child(child?: widget)

Replaces current active child with a new one and calls the activate/deactivate events of the child. This is especially used to send text input events to widgets with input_text support.

@param child?: widget — If nil deactivates current child

toggle_background​

(method) widget:toggle_background(enable?: boolean)

When set to false the background rendering is disabled.

toggle_play​

(method) core.audioview:toggle_play()

toggle_visible​

(method) widget:toggle_visible(animated?: boolean, lock_x?: boolean, lock_y?: boolean, options?: widget.animation.options)

Toggle visibility of widget.

@param options?: widget.animation.options

try_close​

(method) core.audioview:try_close(do_close: function)

update​

(method) core.audioview:update()

update_if_scaled​

(method) widget:update_if_scaled()

Explicitly call the widget update procedure when the scale change even if the widget is not visible.

update_position​

(method) widget:update_position()

Called on the update function to be able to scroll the child widgets.

update_scrollbar​

(method) core.view:update_scrollbar()

Update scrollbar positions and sizes. Called automatically by update(). Rarely needs to be called manually.

update_size_position​

(method) widget:update_size_position()

Similar to update, but here you should perform expensive calculations that will get executed for a predefined period of time when a widget is initialized, scale has changed or a widget switched from hidden to visible.