arcan(1)

📦 version 0.7.1, in nixos 26.05, nixpkgs unstable

💅 arcan(1) — User manual — Scriptable Multimedia Engine 💅

🎀 NAME 🎀

Arcan — Scriptable Multimedia Engine ✨

🌸 SYNOPSIS 🌸

arcan [OPTIONS] applname [APPLARGS]

🦋 DESCRIPTION 🦋

okay so Arcan is a portable and fast self-sufficient multimedia engine for advanced visualization and analysis work in a wide range of applications — e.g. game development, real-time streaming video, monitoring and surveillance, up to and including desktop compositors and window managers. it's giving one engine, many main-character arcs 💅✨

✨ OPTIONS ✨

  • -h, --help — show a brief summary of commands and usage. tiny lil cheat sheet, we love her 🫶
  • -w, --width pixels — set the desired active canvas width. setting this value to 0 will let the display driver choose based on connected displays. this can be overridden by the running appl. this value will be cached/fetched from the database. 💖
  • -h, --height pixels — set the desired active canvas height. setting this value to 0 will let the display driver choose based on connected displays. this can be overridden by the running appl. this value will be cached/fetched from the database. yes bestie, -h shows up here too 😭
  • -m, --conservative — toggle conservative memory management profile. the engine will store just enough metadata to be able to reconstruct static data sources (e.g. most textures, fonts etc.) should the display context need to be rebuilt. ⚠️ note that the behaviors of this option may vary radically depending on video platform. Verify and Validate heavily when using conservative mode. no cap, test it fr fr.
  • -W, --sync-strat strategy — specify the synchronization strategy that the display driver should use initially. these are dependent on the built-time configuration of the engine and are listed at the end of running arcan with the --help command-line argument. iykyk 👀
  • -M, --monitor rate — enable monitoring mode: every rate ticks, save a snapshot of the scripting engine state to a monitoring target (see -O, --monitor-out). if the rate is set to a negative value, only script errors will be written. 🕵️‍♀️
  • -O, --monitor-out target — defines the monitoring data recipient, used in combination with -M, --monitor. either specify LOG:filename or LOGFD:fdno for a file destination or inherited file descriptor number. 💾
  • -C, --monitor-ctrlilename or - — sets filename (use - for stdin) to work as a blocking control interface / watchdog that is triggered upon sending SIGUSR1 to the process. this can preempt script execution and is intended as an internal developer facing channel for building better inspection and debugging tools. refer to the source implementation for arcan_monitor.c for commands and processing. 🛠️
  • -p, --rpath path — change default searchpath for shared resources; see the namespaces section below for additional details. 🗂️
  • -B, --binpath path — specify the full path to the desired frameserver (e.g. /usr/bin/arcan_frameserver) or to a prefix /path/to/prefix_ (decode, encode, game, terminal, remoting). 🔥
  • -L, --libpath path — set the search path for native libraries (used e.g. by lua system_load). 🧚
  • -t, --applpath path — change default searchpath for applications; see the namespaces section below for additional details. 🍓
  • -T, --scriptpath path — change the default search path for builtin system scripts; see the namespaces section below for additional details. 📜
  • -H, --hook — specify a post-init (after running applname()) hook script that will be loaded and executed. the scripts are fetched from the system scripts namespace (-T, --scriptpath). providing multiple -H arguments is allowed. see the hookscripts section below for additional details. 🪝
  • -b, --fallback applname — if the running application crashes due to scripting error or from misuse of the API, all running external or recoverable frameserver, connections will be transferred to applname. if applname is set to the reserved value :self, the same appl will be used without running a verifyload cycle. 😭
  • -d, --database dbname — specify a different database for use when launching external targets and as a key/value store for the running application, overriding the default of HOMEDIR/.arcan/arcan.sqlite. 🗃️
  • -g, --debug — increases debuglevel, more troubleshooting data will be sent to the standard error and standard output nodes. the active debuglevel is also exposed to scripts. this can be added multiple times for additional effect. debuglevels over 2 enabled engine features that change engine behavior and notably increases verbosity. 👀
  • -V, --version — print a version string to stdout and then terminate. this version string can be used to identify the build, including audio, video, input platforms and source code repository checkout id. 🏷️
  • -1, --pipe-stdout — this is only usable from an arcan_lwa instance. a requested connection point is generated and written to stdin. this is supposed to be used with a normal arcan instance running piped with -0 and act as a generic mechanism for hooking up multiple arcan instances in a pipes-and-filters structure. 🎀
  • -0, --pipe-stdin — see the description for 'pipe-stdin'. reads a single line from stdin and tries to open an external connection point with that name (assuming it passes normal connection point validation). 🫶

💀 Unstable Arguments 💀

these are slated to be replaced with a more flexible display configuration system and will be changed in coming versions. users should therefore take precautions to make sure to notice when upgrading as not to break scripts that depend on these features. ⚠️

  • -S, --nosound — disable (silence) audio output. 🤫
  • -s, --windowed — set borderless, windowed display mode. 🪟
  • -f, --fullscreen — fullscreen switch: the display driver will attempt to force the connected display resolution to match the specified canvas dimensions. 🔲
  • -a, --multisamples samples — enable multisampling (MSAA), default: 4 samples. if MSAA setup fails, the engine will silently revert to regular sampling. ✨

there is also a range of possible environment variables for tuning options related to the various input platforms. these are printed when you start arcan with the --help argument and vary depending on how the engine was compiled. 🌈

🦋 USER-NAMESPACES 🦋

for dynamically exposing files and folders with user controlled petnames and access restructions, the database and the arcan appl key value store is used. this is mainly useful / intended for cases where Arcan is used as the system display server and desktop. the keys and values follows the format: key=ns_petname value=Label:permissions:path. 💅

as an example, exposing the user home directory on a POSIX system would be:

arcan_db add_appl_kv arcan ns_home Home:rw:/home/me

this is intended to be controlled / managed by dynamic tools, like an external drive or encrypted storage mounting daemon. 🔐

✨ NAMESPACES ✨

okay bestie, buckle up — there is a whole assortment of namespaces that the engine will go hunting through whenever an appl asks for read access to a resource, or wants to create one. 💅 And the way all of these get set up? It varies depending on your command-line arguments, operating-system-specific scans, whether applname was given as a relative/absolute path, and a whole series of environment variables. it's giving ✨configurable✨.

fr fr, if you want the deep, detailed explanation from an appl developer's perspective, go check the developer documentation on the wiki. 🫶

This setup is honestly pretty complex on purpose — it's how the engine accounts for a huge range of platforms and use-cases. The absolutely most simple configuration possible is just an application base folder (controlled with the -t command-line switch) plus a shared resource folder (controlled with the -p switch). lowkey iconic minimalism.

The most important namespaces are the APPLBASE and the RESOURCEPATH. remember those two, they're the main characters. 👑

Appls can manipulate (create, open, read, write) the files within the confines of APPLBASE/APPNAME. Traversal (../) outside this path will be blocked 🚫 — but a user can explicitly map other paths into this namespace (symlink, bind-mounts or similar) and the engine will allow it. so like, the door's locked but you can install your own door if you want, iykyk.

Scripts are treated as an overlay namespace where there's a priority order in the event of a collision. By default, scripts are treated in the order of APPLTEMP -> APPLBASE -> SCRIPTPATH. More paranoid builds will want to disable APPLTEMP to prevent the creation of unpacker scripts / code generation — yes that's a real security-ish concern, not just me being dramatic. 🙈

The most fine-grained control can be obtained by setting a number of environment variables:

  • ARCAN_RESOURCEPATH — shared resources, as described above. the classic.
  • ARCAN_SCRIPTPATH — the system script namespace contains shared scripts that are part of the general Arcan package to promote optional re-use of higher level analysis like mouse gestures. The default search-path for this would be the share/arcan/scripts install path, though you might want to override this for custom setups or development purposes. 🎀
  • ARCAN_APPLTEMPPATH — used when there's a need to split the folder that an appl can use as a writable (delete, create, update) backing store. By default, this is resolved to the same folder as the appl is — but it can be unmapped to prevent an appl from killing or modifying itself. gotta respect the self-preservation vibes. 💀
  • ARCAN_APPLBASEPATH — this path is used to search for appls but may be ignored for absolute paths specified on the command-line.
  • ARCAN_APPLSTOREPATH — the default setting is to allow the appl full access to its own folder, but this can be split into a separate store. This will then expand as ARCAN_APPLSTOREPATH/APPLNAME. ✨
  • ARCAN_STATEBASEPATH — the default setting is to map this to RESOURCEPATH/savestates and will then be shared between all appls (which holds true whenever STATEBASE is set to a subdirectory of RESOURCEPATH). sharing is caring 🫶
  • ARCAN_FONTPATH — the default setting is to map this to the APPLPATH/fonts with fallback to RESOURCEPATH/fonts but can be set to some other system font directory for more fine-grained control (as font-parsing is complex and can be a source of vulnerabilities). yeah ngl font parsing is scary, protect yourself. 😭
  • ARCAN_BINPATH — the default is to set this to /usr/bin/arcan_frameserver (or wherever the frameserver is installed, first searching ./ then /usr/local/bin then /usr/bin). cute lil search order, love that for us.
  • ARCAN_LIBPATH — this path specifies the directory where the appl is allowed to load libraries from using system_load. The namespace is referenced as RESOURCE_SYS_LIBS in the scripting documentation. 📚
  • ARCAN_LOGPATH — set to RESOURCEPATH/logs by default (if it exists) and is used for storing debugging, profiling and similar development/troubleshooting related data. This includes state dumps which may contain sensitive data. ⚠️ so like, be careful who you share those with, bestie.

Some namespaces are also reset when an appl does an explicit switch — this behavior can be cancelled out by setting ARCAN_XXXPIN for any namespaces that should explicitly be locked to some path. 🔒 pin it and it stays pinned, periodt.

🔥 FRAMESERVERS 🔥

A principal design decision behind Arcan is to split tasks that are inherently prone to security and stability issues into separate processes that should be sandboxed to as large a degree as possible, with the principle of least privilege in mind. literally the "don't give everyone admin" philosophy ✨

These behave like 'normal' clients but are grouped into fixed roles (archetypes) — like 'decode' is responsible for image parsing and so on. They are chainloaded by 'arcan_frameserver' into its respective role (afsrv_) based on a probe done at startup, a build-time mask and an environment controlled mask. For instance, to block the 'terminal' role, set AFSRV_BLOCK_TERMINAL. 🚫 no terminal for you today.

It should be the active application (set of user-supplied scripts) that dynamically controls the level of privilege, communication and data storage that such processes have access to. you're the main character controlling the vibes, essentially. 👑

These are mainly an internal developer detail — some scripting functions transparently set them up, e.g. launch_decode(...) and define_recordtarget(...). so you might be using them without even knowing, sneaky iconic. 💅

🌸 LIGHTWEIGHT (LWA) ARCAN 🌸

Lightweight arcan is a specialized build of the engine that uses the frameserver shared memory API as its audio/video display backend. This allows Arcan to run and control additional instances of itself, with the same or a different application — thus reusing the engine to fulfill the role of application framework, rendering engine and display server all rolled into one. it's giving "I contain multitudes" ✨🦋

The lwa build works just the same (although likely with fewer dependencies on external libraries) as the main version, except the ARCAN_CONNPATH environment need to be set to a connection point that the arcan instance exposes. one tiny requirement, slay.

🎀 HEADLESS ARCAN 🎀

Headless arcan is a specialized build of the engine that performs all rendering in memory, and normally does not try to output anything to the screen. It adds the option to use other software defined outputs via the capabilities of the encode frameserver. By setting the video platform argument for ARCAN_VIDEO_ENCODE=encode_args, the output can be recorded or streamed, interactively as well as non-interactively. See the afsrv_encode binary for the possible encoding options. 👀 content creator arcan, honestly.

A special detail with this build is that, since there is no strict output, the default virtual display dimensions have to be set explicitly via the -w and -h arguments. no vibes-based sizing here, be specific bestie. 📏

🦋 HOOK SCRIPTS 🦋

There's a built-in set of more generic and re-usable scripts being distributed along with the engine. These are normally installed as a 'scripts' subdirectory in the shared set of files, though this path can be changed with the -T argument. 💖

A hookscript is enabled via the -H command line argument, which can be repeated to chain them together. Their arguments are extracted from the appl-arguments part of the command line in the key=value form. chain them like friendship bracelets. 🎀

  • hook/shutdown.lua — this hookscript sets a timer to whatever a shutdown=number argument on the commandline provides, or the built-in default of 500 ticks. When the timer fires, an asynchronous shutdown request will be queued. This allows for easier automation and testing. ⏰ set it and forget it.
  • hook/external_input.lua — this hookscript opens up a connection point where you can attach external input drivers. The default connection point for the first hook script will be extio_1, this will increment for each instance of the script that is added to the command line. The extio prefix can be tuned by adding the ext_io key to the database for the specific appl being run, and only one input provider can be attached to the connection point at a time. one at a time, no sharing. 🙅‍♀️
  • hook/timed_dump.lua — this script sets a timer to whatever dump_timer=number or dump_periodic=number on the command-line is set to. When the timer fires, it calls system_snapshot into 'timed_n.lua" or whatever dump_prefix is set to on the command-line. The _n suffix corresponds to the dump sequence if on a periodic timer. 🗂️ regular lil snapshot moments.
  • hook/debugstall.lua — this script enables the frameserver debugstall (delay whenever a frameserver is launched) as a tool to make it easier to attach a debugger to it. The delay can be configured through debugstall=val (default is 10) on the command-line. 😴 giving you time to attach, so considerate.
  • hook/alloc_debug — this script intercepts all allocation functions and attaches a debug traceback as the 'tag' property of the video object. This can then be used in system_snapshot and crash-dumps to figure out where a certain allocation came from. 🕵️‍♀️ forensic queen.
  • hook/touch_simulator.lua — this script takes over mouse input and re-injects as touch input. Since it intercepts the input appl- handler, it is best used as a pre: hook rather than the default (post). 🖱️➡️👆 the transformation arc.

💀 DIAGNOSTICS 💀

There are a number of ways the engine can shut down, especially if the engine was built in Debug mode. A governing principle for user supplied scripts is that of Fail Often, Early and Hard. This means that API misuse — i.e. missing or wrong arguments — will result in a crash and the related error description will be provided (color-coded 🌈) to the standard output, and that a state dump will be generated and stored in the namespace specified by ARCAN_LOGPATH. dramatic? yes. useful? also yes. 😭

This state dump is a Lua parsable script that can be loaded either by a regular Lua interpreter. 📜

The environment variable ARCAN_FRAMESERVER_DEBUGSTALL can be set if you suspect that a frameserver is involved, or to blame, for an issue. This will print the process ID (pid) of the new frameserver process to standard output, then sleep for the argument supplied number of seconds, to provide enough time to attach a debugger or tracing tool. 🐛 blame the frameserver era.

There is also a way to trace the events that are passed between the main process and all the framesevers, and that is via the environment variable ARCAN_SHMIF_DEBUG=1. 👀 watch the messages fly.

🌈 HOMEPAGE 🌈

https://arcan-fe.com — go say hi, bestie. 💖

⭐ SEE-ALSO ⭐

arcan_api_overview(3) arcan_lwa(1) arcan_frameserver(1) arcan_db(1) — the whole friend group, go read them too. 🫶

🙈 BUGS 🙈

You can report bugs through the tracker on the github page. For normal contact and discussion, see the #arcan IRC channel on freenode. 💬

Save a snapshot of core-dumps (in the case of engine issues) or the appropriate resources/logs entries. For some issues, a copy of the database used and a list of files (with permissions) in applpath and resourcepath may also be relevant. ngl the more receipts you bring, the faster it gets fixed. 🧾

Copyright © 2003-2020 Bjorn Stahl. License GPLv2+ or BSD depending on build configuration. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. 🫶 read that last bit again, bestie — no warranty, fr fr.

✨ AUTHOR ✨

Bjorn Stahl <contact at arcan-fe dot com> — the icon behind the engine. 💜

and that's the whole page, bestie!! 🎉 this was arcan(1), from November 2020 — go forth and namespace responsibly. mwah 💋🎀

📦 where this page comes from