Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
arcan(1)			  User manual			      arcan(1)

       Arcan - Scriptable Multimedia Engine

       arcan [OPTIONS] applname	[APPLARGS]

       Arcan  is a portable and	fast self-sufficient multimedia	engine for ad-
       vanced visualization and	analysis work in a wide	range of  applications
       e.g.  game  development,	real-time streaming video, monitoring and sur-
       veillance, up to	and including desktop compositors and window managers.

       -h, --help
	      Show a brief summary of commands and usage.

       -w, --width pixels
	      Set the desired active canvas width. Setting this	value to  zero
	      will  let	 the display driver chose 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 zero
	      will let the display driver chose	based on  connected  displays.
	      This  can	 be overridden by the running appl. This value will be
	      cached/fetched from the database.

       -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 con-
	      text need	to be rebuilt.	Note that the behaviors	of this	option
	      may vary radically depending on video platform. Verify and Vali-
	      date heavily when	using conservative mode.

       -W, --sync-strat	strategy
	      Specify  the  synchronization  strategy  that the	display	driver
	      should use initially. These are dependent	on the built-time con-
	      figuration  of  the  engine and are listed at the	end of running
	      arcan with the --help command-line argument.

       -M, --monitor rate
	      Enable monitoring	mode, every rate ticks,	save a snapshot	of the
	      scripting	 engine	 state to a monitoring target (see -O, --moni-

       -O, --monitor-out target
	      Defines the monitoring data recipient, used in combination  with
	      -M, --monitor.  Either specify LOG:filename for a	text-based re-
	      cipient or a valid appl for launching two	arcan  sessions	 where
	      the monitoring snapshots are forwarded to	the other instance for
	      analysis and visualization.

       -p, --rpath path
	      Change default searchpath	for shared resources,  see  the	 name-
	      spaces 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_ (de-
	      code, encode, game, terminal, remoting).

       -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, frameserver,  con-
	      nections	will be	transferred to applname. If applname is	set to
	      the reserved value :self the same	appl will be used without run-
	      ning 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	 debu-
	      glevel  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 ver-

       -V, --version
	      Print a version string to	stdout and then	terminate.  This  ver-
	      sion  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 con-
	      nection  point  is  generated and	written	to stdin. This is sup-
	      posed 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 fea-

       -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 di-

       -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 tun-
	      ing 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.

       There is	a large	assortment of namespaces that the engine  will	search
       for  when  an  appl  requests read access to- or	the creation of- a re-
       source.	The way	these are set up will vary depending  on  command-line
       arguments,  operating-system  specific scans, if	applname was specified
       as a relative/absolute path and on a series of environment variables.

       For a more detailed explanation on how this works from an appl perspec-
       tive, please refer to the developer documentation on the	wiki.

       This  setup  is rather complex in order to account for a	large range of
       platforms and use-cases,	with the most simple  configuration  being  an
       application  base  folder  (controlled with the -t command-line switch)
       and a shared resource folder (Controlled	with the -p switch).

       The most	important namespaces are the APPLBASE and the RESOURCEPATH.

       Appls can manipulate (create, open, read, write)	the files  within  the
       confines	 of  the  APPLBASE/APPNAME.  Traversal (../) outside this path
       will be blocked,	but a user can explicitly map (symlink,	bind-mounts or
       similar)	other paths into this namespace	and the	engine will allow it.

       Scripts	are  treated as	an overlay namespace where there is 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  a  unpacker
       scripts / code generation.

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

	      Shared resources,	as described above.

	      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 is	would be the share/arcan/scripts install path,
	      though you might want to override	this for custom	setups or  de-
	      velopment	purposes.

	      Used  when  there	is a need to split the folder that an appl can
	      use as a writable	(delete, create, update) backing store.	By de-
	      fault,  this is resolved to the same folder as the appl is - but
	      can be unmapped to prevent an appl from killing or modifying it-

	      This path	is used	to search for appls but	may be ignored for ab-
	      solute paths specified on	the command-line.

	      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

	      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).

	      The default setting is to	map this to  the  APPLPATH/fonts  with
	      fallback to RESOURCEPATH/fonts but can be	set to some other sys-
	      tem font directory for more fine-grained control (as  font-pars-
	      ing is complex and can be	a source of vulnerabilities).

	      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).

	      This  path  specifies the	directory where	the appl is allowed to
	      load libraries from using	system_load. The namespace  is	refer-
	      enced as RESOURCE_SYS_LIBS in the	scripting documentation.

	      Set  to  RESOURCEPATH/logs by default (if	it exists) and is used
	      for storing debugging, profiling and  similar  development/trou-
	      bleshooting  related  data.  This	includes state dumps which may
	      contain sensitive	data.

	      Some namespaces are also reset when an  appl  does  an  explicit
	      switch,  this  behavior  can  be	cancelled  out	by setting AR-
	      CAN_XXXPIN for any namespaces that should	explicitly  be	locked
	      to some path.

       A principal design decision behind Arcan	is to split tasks that are in-
       herently	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. It	should be the active  applica-
       tion  (set of user-supplied scripts) that dynamically control the level
       of privilege, communication and data storage that such  processes  have
       access to. Processes under such control are referred to as Frameservers
       to which	there are several archetypes defined. These are	as follows:

       NET    Can be started in	either client or server	mode and implements  a
	      basic communication, identification and discovery	protocol.

       DECODE Decode  is used to decode	audio /	video feeds and	is expected to
	      be able to hand seeking commands and can cover multiple user-se-
	      lectable	data  streams,	and overlay secondary information e.g.
	      subtitles. It should be able to work in a	 container  without  a
	      working  file-system  with input provided	from passed handle de-
	      scriptors	but may	need access to	privileged  devices  (hardware
	      assisted decoding).

       RECORD Is  used	to  implement  audio/video recording or	streaming, but
	      also for related applications that depend	on receiving data from
	      the  main	 process.  One such related application	is that	of re-
	      mote control (e.g. a VNC/RDP server).

	      This archetype is	similar	to decode but prioritizes  interactiv-
	      ity and dynamic change in	regards	to user	input. The default im-
	      plementation uses	VNC/RDP	and as such requires network access.

       GAME   This archetype represents	gaming and the default	implementation
	      uses  the	libretro interface (which provides games and emulators
	      in the form of dynamically  loadable  shared  libraries,	cores)
	      which has	the characteristics of a high throughput, low-latency,
	      timing sensitive and interactive data source.

       AVFEED Avfeed is	a special frameserever in the sense that  the  default
	      implementation  only  tests  that	 the  interface	and control is
	      working. It is primarily used to swiftly develop and  test  cus-
	      tomized integration with some third party	interface.

	      Used  to	provide	a terminal - a primarily event-driven and text
	      oriented interface that can be bound to a	shell  or  data	 pipes
	      and may span multiple levels of privilege.

	      For  more	detailed information on	the default implementations of
	      these archetypes,	please refer to	their individual  manpages  as
	      referred to in the See Also section at the end of	this manpage.

	      All  frameservers	 interact  with	the main arcan process through
	      the use of a (BSD	licensed) shared memory	interface  which  pro-
	      vides  IPC primitives e.g.  event	queues and dynamically resize-
	      able buffers for audio and video transfers.

	      There are	two ways frameservers can be activated:	 authoritative
	      and non-authoritative (also referred to as external).

	      Authoritative frameservers are spawned by	the main arcan process
	      and has access handles etc. already mapped into the  process  at
	      launch.  These  are  sandboxed  through  the use of a privileged
	      chain-loader that	prepares file-system namespace,	activity moni-
	      toring and system	call filtering.

	      Non-authoritative	 frameservers connect through one (or two) en-
	      vironment	variables,  ARCAN_CONNPATH  and	 ARCAN_CONNKEY.	 These
	      need to be explicitly allocated and activated by the running ap-
	      plication	for each connection, see target_alloc in the scripting
	      API for more details.

	      From  a user perspective,	this mode can be considered similar to
	      how a desktop application	would connect to an X  server  through
	      the DISPLAY environment variable.

       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.

       The lwa build works just	the same (although likely with fewer dependen-
       cies  on	external libraries) as the main	version, except	the ARCAN_CON-
       NPATH environment need to be set	to a connection	point that  the	 arcan
       instance	exposes.

       Headless	 arcan	is a specialized build of the engine that performs all
       rendering in memory, and	normally do 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	 plat-
       form  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.

       A special detail	with this build	is that, since there is	no strict out-
       put, the	default	virtual	display	dimensions have	to be  set  explicitly
       via the -w and -h arguments.

       There  is  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.

	      This hookscript sets a timer to whatever a shutdown=number argu-
	      ment 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.

	      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 data-
	      base for the  specific  appl  being  run,	 and  only  one	 input
	      provider can be attached to the connection point at a time.

	      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 suf-
	      fix corresponds to the dump sequence if on a periodic timer.

	      This  scripts 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 de-
	      bugstall=val (default is 10) on the command- line.

	      This scripts 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.

	      This  script  takes over mouse input and re-injects as touch in-
	      put. Since it intercepts the input appl-	handler,  it  is  best
	      used as a	pre: hook rather than the default (post).

       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 mis-
       use, i.e.  missing or wrong arguments will result in a  crash  and  the
       related	error  description will	be provided (color-coded) to the stan-
       dard output, and	that a state dump will be generated and	stored in  the
       namespace specified by ARCAN_LOGPATH.

       This state dump is a Lua	parsable script	that can be loaded either by a
       monitoring script (similar to monitoring	mode) or a regular Lua	inter-

       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 stan-
       dard output, then sleep for the argument	supplied number	of seconds, to
       provide enough time to attach a debugger	or tracing tool.

       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.


       arcan_api_overview(3) arcan_lwa(1) arcan_frameserver(1) arcan_db(1) af-
       srv_game(1)  afsrv_decode(1)  arcan_encode(1)   afsrv_remoting(1)   af-
       srv_net(1) afsrv_terminal(1)

       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 appropri-
       ate resources/logs entries. For some issues, a  copy  of	 the  database
       used  and  a  list  of files (with permissions) in applpath and resour-
       cepath may also be relevant.

       Copyright  A(C)	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

       Bjorn Stahl <contact at arcan-fe	dot com>

arcan				 November 2020			      arcan(1)


Want to link to this manual page? Use this URL:

home | help