Player API

The js-dos player provides a single entry point: the Dos function. It takes two arguments:

the element where the player window should be created
an options object to configure the player

Dos(element: HTMLDivElement, options: DosOptions) => DosProps;

It returns DosProps, which you can use to control the created player.

Options

option	description	type	default
url	URL to a js-dos bundle	URL
dosboxConf	If you omit `url`, this will be used to configure DOSBox. See example.	string
jsdosConf	Additional js-dos configuration (`jsdos.json`) used with `dosboxConf`.	object	`{}`
initFs	Additional files to initialize the file system. Read more.	`Uint8Array`, `{ path: string, contents: Uint8Array }`, or an array of these entries
background	Background image of the player window.	URL
pathPrefix	Path prefix for emulators deployment files.	string	`https://v8.js-dos.com/latest/emulators/`
pathSuffix	Suffix appended to emulator deployment file paths.	string	`""`
theme	Color theme of the player.	light, dark, cupcake, bumblebee, emerald, corporate, synthwave, retro, cyberpunk, valentine, halloween, garden, forest, aqua, lofi, pastel, fantasy, wireframe, black, luxury, dracula, cmyk, autumn, business, acid, lemonade, night, coffee, winter	light or dark by system preference
lang	Player language.	en, ru	auto
backend	Default backend.	dosbox, dosboxX	dosbox
backendLocked	Prevents changing the backend from the UI.	boolean	false
backendHardware	Function that returns a hardware backend endpoint for the selected backend.	`(backend: "dosbox" \\| "dosboxX") => Promise<string \\| null>`
workerThread	Run the backend in a Worker.	boolean	true
offscreenCanvas	Use `OffscreenCanvas` for rendering when available.	boolean	false
mouseCapture	Lock the mouse in the player window.	boolean	false
fullScreen	Automatically enter fullscreen mode.	boolean	false
onEvent	Listener for js-dos events.	function
autoStart	Automatically start emulation.	boolean	false
fastForwardOnBoot	Fast-forward boot for the specified number of seconds when a sockdrive bundle is used.	number	0
countDownStart	Set countdown before auto start, in seconds.	number	0
autoSave	Automatically save progress on certain actions, such as exiting fullscreen.	boolean	false
kiosk	Enable kiosk mode; in kiosk mode the player UI is hidden.	boolean	false
imageRendering	Image rendering mode.	pixelated, smooth	pixelated
renderBackend	Renderer for the DOS screen.	webgl, canvas	webgl
renderAspect	Aspect ratio of the output window.	AsIs, 1/1, 5/4, 4/3, 16/10, 16/9, Fit	AsIs
scaleControls	Scale of controls.	number	0.2
mouseSensitivity	Mouse sensitivity.	number	0.5
noCursor	Hide the system cursor.	boolean	false
volume	Sound volume.	number [0..1]	1.0
softKeyboardLayout	Initial virtual keyboard layout. Read more.	`string[] \\| string[][][]`	built-in qwerty layout
softKeyboardSymbols	Initial virtual keyboard symbols.	`Array<Record<string, string>>`	built-in symbols
softFullscreen	If set to `true`, fullscreen will not use the `requestFullscreen()` method. Instead, it will add the `jsdos-fullscreen-workaround` class to the root element. You need to ensure that this element occupies the entire page content.	boolean	false
thinSidebar	Start the player with the thin sidebar.	boolean	false
sockdrivePreload	Controls sockdrive preloading.	none, all, default	default
startIpxServer	Start an IPX server for multiplayer networking.	boolean	false
connectIpxAddress	Connect to an IPX peer ID or registered alias.	string
fsChanges	Options to configure save/load.	object	`{ local: true }`
net	WebRTC networking configuration.	`{ peerServer: string, token: string, secret: string, iceServers: () => Promise<IceServer[]> }`	js-dos defaults
sharedNet	Reuse an existing WebRTC networking instance between players.	`NetInstance`

DosProps

DosProps are properties that you can use to control the player after creation. Use them like this:

const props = Dos(elem, options);
props.setFullScreen(true); // switch to fullscreen mode

property	description	arguments
getVersion	version of js-dos + emulators
getLocalChanges	return current FS changes read more	key
setTheme	switch player theme	theme name
setLang	change language	en, ru
setBackend	change backend	dosbox, dosboxX
setBackendLocked	lock or unlock backend selection	bool
setWorkerThread	select execution mode	bool
setOffscreenCanvas	enable or disable `OffscreenCanvas` rendering	bool
setMouseCapture	enable or disable mouse capture	bool
setBackground	change background image	URL or null
setFullScreen	change fullscreen mode	bool
setAutoStart	change auto start	bool
setCountDownStart	set countdown to auto start in seconds	number
setAutoSave	change auto save mode	bool
setKiosk	change kiosk mode	bool
setImageRendering	change image rendering	pixelated, smooth
setRenderBackend	change render backend (available only before emulation start)	webgl, canvas
setRenderAspect	change render aspect	AsIs, 1/1, 5/4, 4/3, 16/10, 16/9, Fit
setNoCloud	disable/enable cloud feature	bool
setScaleControls	set scale of controls	number
setMouseSensitivity	set mouse sensitivity	number
setPaused	pause/resume emulation	bool
setNoCursor	show/hide system cursor	bool
setVolume	set sound volume	number [0..1]
setSoftKeyboardLayout	set virtual keyboard layout	`string[] \\| string[][][]`
setSoftKeyboardSymbols	set virtual keyboard symbols	map[]
setSoftFullscreen	set soft fullscreen	bool
setThinSidebar	switch between normal and thin sidebar	bool
save	trigger saving FS changes, returns `Promise<boolean>`	-
stop	kill the emulation (use to stop player)	-

setNoCloud(true) hides cloud-related UI. It does not disable local saves; use fsChanges.local: false for that.

Events

You can listen to js-dos events by providing a listener in the Dos function:

Dos(elem, {
    onEvent: (event, ci?: [[[CommandInterface|command-interface.html]]]) => {
       console.log("js-dos event", event); 
    }
});

order	event	description	args
0	emu-ready	when emulators are fully loaded and ready to run the program
1	bnd-play	when play button is clicked
2	ci-ready	when backend is started and CommandInterface is available	CommandInterface
	fullscreen-change	when fullscreen state of player changed	boolean

Stop/Restart player

To stop player and free all used resources, please call props.stop(), after this player is totally disposed.
To restart player dispose current player and start new one.

Typescript

js-dos provides Typescript type declarations. Just put it somewhere in your codebase, and declare Dos function:

import {DosFn} from "types";

declare const Dos: DosFn;

// ...

Dos(element, options)

export type DosEvent = "emu-ready" | "ci-ready" | "bnd-play" | "open-key" | "fullscreen-change"; export type ImageRendering = "pixelated" | "smooth"; export type RenderBackend = "webgl" | "canvas"; export type RenderAspect = "AsIs" | "1/1" | "5/4" | "4/3" | "16/10" | "16/9" | "Fit"; export type SockdrivePreload = "none" | "all" | "default"; export interface IceServer { urls: string | string[]; username?: string; credential?: string; } export type InitBundleEntry = Uint8Array; export interface InitFileEntry { path: string; contents: Uint8Array; } export type InitFsEntry = InitBundleEntry | InitFileEntry; export type InitFs = InitFsEntry | InitFsEntry[]; export type NetInstance = { peerId: number; connected: Set<number>; wait: (ms: number) => void; registerAlias: (alias: string) => Promise<void>; unregisterAlias: (alias: string) => void; queryAliases: (query: string) => Promise<{ peerId: number; }[]>; sendBinary: (data: Uint8Array, peerId: number) => number; recvBinary: () => { data: Uint8Array, peerId: number } | null; disconnect: (peerId: number) => void; shutdown: () => void; } export interface DosOptions { url: string, dosboxConf: string, jsdosConf: any, initFs: InitFs, background: string, pathPrefix: string, pathSuffix: string, theme: "light" | "dark" | "cupcake" | "bumblebee" | "emerald" | "corporate" | "synthwave" | "retro" | "cyberpunk" | "valentine" | "halloween" | "garden" | "forest" | "aqua" | "lofi" | "pastel" | "fantasy" | "wireframe" | "black" | "luxury" | "dracula" | "cmyk" | "autumn" | "business" | "acid" | "lemonade" | "night" | "coffee" | "winter", lang: "ru" | "en", backend: "dosbox" | "dosboxX", backendLocked: boolean, backendHardware: ((backend: "dosbox" | "dosboxX") => Promise<string | null>), workerThread: boolean, offscreenCanvas: boolean, mouseCapture: boolean, onEvent: (event: DosEvent, arg?: any /* CommandInterface | boolean */) => void, fullScreen: boolean, autoStart: boolean, fastForwardOnBoot: number, countDownStart: number, autoSave: boolean, kiosk: boolean, imageRendering: ImageRendering, renderBackend: RenderBackend, renderAspect: RenderAspect, scaleControls: number, mouseSensitivity: number, noCursor: boolean, softKeyboardLayout: string[] | string[][][], softKeyboardSymbols: { [key: string]: string }[], volume: number, softFullscreen: boolean, thinSidebar: boolean, sockdrivePreload: SockdrivePreload, startIpxServer: boolean, connectIpxAddress: string, fsChanges: { local: boolean, urlToKey?: (url: string) => Promise<string>, pull?: (key: string) => Promise<Uint8Array | null>; push?: (key: string, data: Uint8Array) => Promise<void>; delete?: (key: string) => Promise<void>; }, net: { peerServer: string, token: string, secret: string, iceServers: () => Promise<IceServer[]>, }, sharedNet: NetInstance, } export interface DosProps { getVersion(): [string, string]; getLocalChanges(key: string): Promise<Uint8Array | null>; setTheme(theme: DosOptions["theme"]): void; setLang(lang: DosOptions["lang"]): void; setBackend(backend: DosOptions["backend"]): void; setBackendLocked(locked: boolean): void; setWorkerThread(capture: DosOptions["workerThread"]): void; setOffscreenCanvas(offscreenCanvas: DosOptions["offscreenCanvas"]): void; setMouseCapture(capture: DosOptions["mouseCapture"]): void; setBackground(background: string | null): void; setFullScreen(fullScreen: boolean): void; setAutoStart(autoStart: boolean): void; setCountDownStart(countDownStart: number): void; setAutoSave(autoSave: boolean): void; setKiosk(kiosk: boolean): void; setImageRendering(rendering: ImageRendering): void; setRenderBackend(backend: RenderBackend): void; setRenderAspect(aspect: RenderAspect): void; setNoCloud(noCloud: boolean): void; setPaused(pause: boolean): void; setScaleControls(scaleControls: number): void; setMouseSensitivity(mouseSensitivity: number): void; setNoCursor(noCursor: boolean): void; setSoftKeyboardLayout(layout: string[] | string[][][]): void; setSoftKeyboardSymbols(symbols: { [key: string]: string }[]): void; setVolume(volume: number): void; setSoftFullscreen(softFullscreen: boolean): void; setThinSidebar(thinSidebar: boolean): void; save(): Promise<boolean>; stop(): Promise<void>; } export type DosFn = (element: HTMLDivElement, options: Partial<DosOptions>) => DosProps; // declare const Dos: DosFn;

19 июня 2026