Fields

Fields are the settings you define for your widget and the streamer fills in. At runtime, each field is read by its name and returns an object whose shape depends on its type.

getField

breezy.getField<T = any>(name: string): T

Returns the field named name, or null when the streamer has not set a value. The result is cached until the widget's values change.

let title = breezy.getField('title')
let font = breezy.getField('titleFont')

element.textContent = title.text
font.apply(element)

getFields

breezy.getFields(names: Array<string>): FieldList

Returns several fields at once, so their styles can be applied together.

breezy.getFields(['background', 'border', 'shadow']).apply('.card')

Applying fields

Style fields know how to render themselves on an element. apply accepts a CSS selector, an element or a list of elements, plus an optional palette for colors that follow the streamer's accent.

interface Field {
	apply: (element: Selector, palette?: Palette) => void
}

interface FieldList {
	fields: Array<Field>
	apply: (element: Selector, palette?: Palette) => void
}

Field types

Content

interface TextInputField extends Field {
	text: string
}

interface TextAreaField extends Field {
	text: string
}

interface SwitchField extends Field {
	active?: boolean
}

interface SelectField extends Field {
	selection: string
}

interface RadioField extends Field {
	selection: string
}

interface CheckField extends Field {
	selection: Array<string>
}

interface LocationField extends Field {
	selection: string
}

interface MediaField extends Field {
	selection: ID
}

interface WidgetSelectorField extends Field {
	selection: Array<ID>
	widgets: Array<WidgetController>
}

interface MediaDeviceField extends Field {
	deviceId: string
	label: string
	kind: 'video' | 'audio'
	getStream: () => Promise<MediaStream>
}

MediaField.selection is a media ID: load it with getMedia. WidgetSelectorField.widgets gives you a controller for each selected widget.

MediaDeviceField is a camera or microphone picked by the streamer. Apply it to a <video> or <audio> element to play the device, or call getStream to get the MediaStream yourself. An empty deviceId means the system default.

let camera = breezy.getField('camera')
camera.apply('video')

Style

interface FontField extends Field {
	size?: number
	family?: string
	weight?: string
	color?: ColorField
	leading?: number
	kerning?: number
	alignment?: string
	transform?: string
}

interface ColorField extends Field {
	type?: string
	sampleColor?: ColorFieldSampleColor
	accentColor?: ColorFieldAccentColor
}

interface BorderField extends Field {
	width?: number
	style?: string
	color?: ColorField
	radius?: { tl?: number, tr?: number, bl?: number, br?: number }
	target?: Array<string>
}

interface ShadowField extends Field {
	color?: ColorField
	offset?: { x?: number, y?: number }
	radius?: number
	spread?: number
}

interface FilterField extends Field {
	blur: number
	brightness: number
	contrast: number
	saturate: number
	grayscale: number
	sepia: number
	invert: number
	hueRotate: number
	opacity: number
	toString: () => string
}

interface SpacingField extends Field {
	outer?: { t?: number, l?: number, r?: number, b?: number }
	inner?: { t?: number, l?: number, r?: number, b?: number }
}

interface GapField extends Field {
	col?: number
	row?: number
}

interface SizeField extends Field {
	w: number
	h: number
}

interface ImageField extends Field {
	image?: MediaField
	mode?: string
	size?: Size
}

FilterField values are percentages, except blur (px) and hueRotate (deg). apply sets the element's CSS filter; toString returns the same value for use elsewhere, such as a canvas context.

A color is either a sample color (solid, linear or radial gradient) or an accent color taken from a palette:

type ColorFieldSampleColor = {
	type?: string
	color?: ColorFieldSolid
	linearGradient?: { angle?: number, stops?: Array<ColorFieldColorStop> }
	radialGradient?: { shape?: string, stops?: Array<ColorFieldColorStop> }
}

type ColorFieldSolid = {
	r?: number
	g?: number
	b?: number
	a?: number
}

type ColorFieldColorStop = {
	value?: number
	color?: ColorFieldSolid
}

type ColorFieldAccentColor = {
	color?: string
	alpha?: number
	shade?: number
}

Behavior

interface TransitionField extends Field {
	name?: ID
	duration?: number
	easing?: string
	delay?: number
	play: (element: HTMLElement) => Promise<void>
}

interface DisplayField extends Field {
	when?: string
	timers?: Array<{ duration?: number, interval?: number }>
	events?: Array<{ name: string, duration?: number, cooldown?: number }>
	enterTransition?: TransitionField
	leaveTransition?: TransitionField
}

interface VoiceField extends Field {
	voice: string
	pitch: number
	volume: number
	speak: (text: string) => Promise<void>
}

let voice = breezy.getField('voice')
await voice.speak('Thanks for the follow!')

Layout

GroupField and PanelField organize other fields in the editor and carry no value of their own.