zebar

## ⚙️ Installation **Downloads for Windows, MacOS, and Linux are available in the [latest release](https://github.com/glzr-io/zebar/releases)**. For building locally, follow the instructions [here](https://github.com/glzr-io/zebar/blob/main/CONTRIBUTING.md). ## Quick start ### Accessing Zebar GUI Click the Zebar icon in your system tray to open the GUI interface. ### Installing widgets Navigate to the marketplace within the GUI to browse and install widget packs. ### Auto-starting widgets Widgets can be set to run on startup by right clicking the Zebar tray icon then going to `Widget packs` -> `` -> `` -> `Run on startup` and clicking the widget name to check it. ## Intro to Zebar Widgets are powered by native webviews (_similar_ to Electron, but more lightweight). ## Creating your own widgets Zebar looks within the `~/.glzr/zebar` directory for directories containing a `zpack.json` file. Each `zpack.json` file defines a widget pack. Each widget pack can contain multiple widgets, each defined individually within the `zpack.json` file. For example, a widget pack config could be located at `~/.glzr/zebar/example-widget/zpack.json`, which would create a widget pack with an id of `example-widget`. Zebar only looks for `zpack.json` files one level deep within the `~/.glzr/zebar` directory, so `~/glzr/zebar/example-widget/widget-1/zpack.json` is invalid. In the `My widgets` tab of the Zebar GUI, you can click `Create new pack` to generate a widget pack scaffold with the given name and description. Within each widget pack, in the `Widgets` section you can click `Add widget` to create a new widget within that pack. When creating a new widget you can pick between some templates to get you started. > Apart from the React buildless template, other available templates require you to have Node.js and a package manager (npm/pnpm) installed. For these templates, run the build command (e.g. pnpm build) from the widget directory after any source code changes. ### Modifying marketplace widgets To edit a marketplace widget without fear of your changes being overridden, you should copy the folder from the marketplace directory (located at `%AppData%/zebar/downloads/`) to your own Zebar directory (located at `~/.glzr/zebar/`). > **DO NOT** re-publish other peoples widgets without permission. ### Advanced Customization #### What is the zpack.json file? Widgets are stored in packs, with each pack being defined by a `zpack.json` file. Each pack can contain multiple widgets, each individually defined within `zpack.json`. Widgets consist of an HTML file, and any surrounding assets (e.g. CSS, JS, images, etc.). The schema for `zpack.json` can be found [here](https://github.com/glzr-io/zebar/blob/main/resources/zpack-schema.json) although all options can also be configured via the GUI. #### Querying system information Zebar exposes various system information (referred to as "providers") which can be used and displayed by your frontend. This includes stats like CPU usage, battery info, various window manager integrations, and lots more. See [Providers](#-providers) for a list of available providers. ## ❓ FAQ **Q: Help! On Windows, Zebar is failing to start?** In some cases, updating to the latest Microsoft Webview2 version is needed ([standalone download](https://developer.microsoft.com/en-us/microsoft-edge/webview2/?form=MA13LH#download)). Run the "Evergreen Standalone Installer" as administrator. ## Providers Through the `zebar` NPM package, Zebar exposes various system information via reactive "providers". Providers are a collection of functions and variables that can change over time. - [audio](#audio) - [battery](#battery) - [cpu](#cpu) - [date](#date) - [disk](#disk) - [glazewm](#glazewm) - [host](#host) - [ip](#ip) - [keyboard](#keyboard) - [komorebi](#komorebi) - [media](#media) - [memory](#memory) - [network](#network) - [systray](#systray) - [weather](#weather) ### Audio #### Config No config options. #### Outputs | Variable | Description | Return type | Supported OS | | ------------------- | ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `defaultPlaybackDevice` | Default audio playback device. | `AudioDevice \| null` | | | `defaultRecordingDevice` | Default audio recording device. | `AudioDevice \| null` | | | `playbackDevices` | All audio playback devices. | `AudioDevice[]` | | | `recordingDevices` | All audio recording devices. | `AudioDevice[]` | | | `allDevices` | All audio devices (both playback and recording). | `AudioDevice[]` | | | Function | Description | Return type | Supported OS | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `setVolume` | Sets the volume of an audio device. Changes the volume of the default playback device, unless `SetVolumeOptions.deviceId` is specified.

**Parameters:**
- `volume`: _`number`_ Volume as a % of maximum volume. Returned value is between `0` and `100`.
- `options`: _`SetVolumeOptions \| undefined`_ Additional options.
| `Promise` | | #### Related types #### `AudioDevice` | Variable | Description | Return type | | ------------------ | ----------------------------- | ----------------------- | | `deviceId` | Device ID. | `string` | | `name` | Friendly display name of device. | `string` | | `volume` | Volume as a % of maximum volume. Returned value is between `0` and `100`. | `number` | | `type` | Type of the device. | `'playback' \| 'recording'` | | `isDefaultPlayback` | `true` if the device is selected as the default playback device.| `boolean` | | `isDefaultRecording` | `true` if the device is selected as the default recording device.| `boolean` | #### `SetVolumeOptions` | Variable | Description | Return type | | ------------------ | ----------------------------- | ----------------------- | | `deviceId` | Device ID to set the volume of. | `string \| undefined` | ### Battery #### Config | Option | Description | Option type | Default value | | ------------------ | -------------------------------------------------- | ----------- | ------------- | | `refreshInterval` | How often this provider refreshes in milliseconds. | `number` | `5000` | #### Outputs | Variable | Description | Return type | Supported OS | | ------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chargePercent` | Battery charge as a percentage of maximum capacity (aka. 'state of charge'). Returned value is between `0` to `100`. | `number` | | | `healthPercent` | Condition of the battery as a percentage of perfect health. Returned value is between `0` to `100`. | `number` | | | `cycleCount` | Number of charge/discharge cycles. | `number` | | | `state` | State of the battery. | `'discharging' \| 'charging' \| 'full' \| 'empty' \| 'unknown'` | | | `isCharging` | Whether the battery is in a `charging` state. | `boolean` | | | `timeTillEmpty` | Approximate time in milliseconds till battery is empty. | `number \| null` | | | `timeTillFull` | Approximate time in milliseconds till battery is fully charged. | `number \| null` | | | `powerConsumption` | Battery power consumption in watts. | `number` | | | `voltage` | Battery voltage. | `number \| null`