Python API

qast exposes a clean Python API for automation, scheduled playback, and digital signage.

Public exports

from qast import discover, cast, Qast, Device, Status, QueueItem

Device discovery

from qast import discover

# Discover all TVs on the LAN (5-second scan)
devices = discover()

for d in devices:
    print(f"{d.name} [{d.protocol}] {d.host}:{d.port}")

# Extended scan with all protocol variants
devices = discover(timeout=15, show_all=True)

discover()

Parameter	Type	Default	Description
`timeout`	int	15	Discovery timeout in seconds
`show_all`	bool	False	Include all protocol variants per device

Returns list[Device]. Each Device has name, protocol, host, port.

One-shot casting

from qast import discover, cast

devices = discover()

# Cast a URL
cast("https://youtube.com/watch?v=dQw4w9WgXcQ", device=devices[0])

# Cast a local file with duration limit
cast("video.mp4", device=devices[0], duration=60)

# Cast desktop for 30 seconds
cast("screen", device="roku", duration=30)

# Cast with YouTube cookies
cast("https://youtube.com/watch?v=...",
     device="Living Room TV",
     cookies_from_browser="chrome")

cast()

Parameter	Type	Description
`source`	str	URL, file path, or capture source
`device`	Device \| str \| int	Target device, name, or index
`duration`	int \| None	Max playback seconds
`repeat`	bool	Loop playback
`shuffle`	bool	Randomize order
`cookies_from_browser`	str \| None	Browser for cookie extraction

Queue-based playback

from qast import Qast

# Create a queue targeting a specific device
q = Qast(device="Living Room TV")

# Add sources with optional durations
q.add("https://youtube.com/watch?v=VIDEO1")
q.add("~/Videos/workout.mp4", duration=300)
q.add("screen", duration=30)
q.add("window:Grafana", duration=120)

# Start playback
q.play()                          # play once
q.play(repeat=True)               # loop forever
q.play(repeat=True, shuffle=True) # loop + shuffle

# Dynamic control during playback
q.skip()       # skip to next item
q.remove(2)    # remove item at index
q.stop()       # stop playback

Queue status

# Get current playback status
status = q.status()

print(status.state)        # "playing", "stopped", etc.
print(status.now_playing)  # current source string
print(status.duration)     # elapsed seconds
print(status.position)     # current queue position
print(status.queue)        # list of QueueItem objects

Status fields

Field	Type	Description
`state`	str	Current state (playing, stopped, etc.)
`now_playing`	str	Active source
`duration`	float	Elapsed playback time
`position`	int	Queue index
`queue`	list[QueueItem]	All queued items

Use cases

Digital signage: Loop dashboards, videos, and web pages on a lobby TV.
Scheduled playback: Use cron + Python to cast content at specific times.
Monitoring: Cast Grafana dashboards or security cameras to a wall display.
Testing: Automate TV protocol testing across Chromecast, DLNA, and Roku.

References

Created by Rich LeGrand · MIT License