# Closeup: API reference

> Everything the package exports: opening it, actions on a take, scripts, and their types.

Source: https://cesarvenzac.com/closeup/docs/api

## Opening it

### install(options?)

Opens and closes Closeup on a shortcut, ⌥⇧C unless told otherwise. Returns what removes it.

```typescript
function install(options?: { shortcut?: string }): () => void;
```

### open(options?), close(), toggle()

Opens Closeup, on `pick` when given an element, ready to film; closes it; or one or the other.

```typescript
function open(options?: { pick?: Element | null }): void;
function close(): void;
function toggle(): void;
```

### DEFAULT\_SHORTCUT

`"Alt+Shift+C"`.

### supportsCapture()

Whether this browser can share a tab and crop it to an element.

## Takes

### addAction(action)

Offers a button of your own on every take from now on. Returns what takes it away.

```typescript
function addAction(action: TakeAction): () => void;

type TakeAction = {
  label: string;
  icon?: string; // paths on a 24-unit grid
  when?: (take: Take) => boolean;
  run: (
    take: Take,
    context: { progress: (done: number) => void },
  ) => Promise<string | void>;
};

type Take = {
  kind: "photo" | "video";
  blob: Blob;
  type: string;
  width: number;
  height: number;
  seconds?: number;
  script?: Script; // the script a video played
};
```

## Scripts

### parseScript(value)

A script, checked, from JSON already parsed: `null` if it isn't one.

### loadScript(path?), saveScript(script, path?)

The script kept in this browser for a page, by its path (the current page's unless said); saving `null` forgets it.

```typescript
function parseScript(value: unknown): Script | null;
function loadScript(path?: string): Script | null;
function saveScript(script: Script | null, path?: string): void;

type Script = {
  version: 1 | 2;
  start: Target;
  out?: { x: number; y: number };
  steps: Step[];
};
type Step = {
  to: Target;
  in?: { x: number; y: number };
  out?: { x: number; y: number };
  action: "move" | "click" | "type" | "scroll";
  text?: string;
  scroll?: number;
  hover?: number;
  duration?: number;
  wait: number;
};
type Target = {
  x: number;
  y: number;
  on?: { selector: string; u: number; v: number };
};
```

## Settings

`Settings` is the type of what the options keep in the browser, exported for anyone reading them:

```typescript
type Settings = {
  mode: "photo" | "video";
  pick: "element" | "region";
  shape: "16:9" | "1:1" | "4:5" | "9:16" | "free"; // free: the pick's own
  padding: number; // room round the pick, a share of its size
  background: "none" | "color" | "gradient" | "image";
  color: string;
  gradient: number;
  inset: number;
  radius: number;
  shadow: boolean;
  cursor: boolean;
  cursorSize: number;
  ring: boolean;
  moves: "yours" | "script";
  zoom: number; // 1, 1.5 or 2
  countdown: number; // seconds before a video by hand
  timer: number; // seconds before a photo
  clicks: boolean;
  tabAudio: boolean;
  quality: "standard" | "high";
};
```

## Closeup's docs

- [Overview](https://cesarvenzac.com/closeup.md): Film any part of a web page in close-up, sharp at any size, with a drawn cursor and sound.
- [Getting started](https://cesarvenzac.com/closeup/docs/getting-started.md): Install Closeup, open it on a shortcut or on an element, and film a first take.
- [Filming](https://cesarvenzac.com/closeup/docs/filming.md): Picking what to film, the frame and its background, the cursor, and the camera that closes in on clicks and pans as you scroll.
- [Scripts](https://cesarvenzac.com/closeup/docs/scripts.md): Draw the cursor's path once and play it on every take: the editor, what each point does, and the JSON a script is kept as.
- [Keeping a take](https://cesarvenzac.com/closeup/docs/keeping.md): Trim a take, change its speed, keep it as a video or a GIF, and add buttons of your own that send it somewhere.
- [API reference](https://cesarvenzac.com/closeup/docs/api.md): Everything the package exports: opening it, actions on a take, scripts, and their types.