# Player Control

> Use the HowdyGo SDK to navigate embedded demos, control auto-progress, and read player state, with loading behavior and step indices explained.

The Player Control API lets you drive an embedded HowdyGo demo from your own page. Build custom Next and Previous buttons in your own UI, jump to a specific step or chapter, resume or pause auto-progress, and read the current player state.

Use it when you want playback to react to something on your page, like a scroll position or a tab change, instead of relying on the player's built-in controls.

## Getting a controller

[Install the SDK](https://docs.howdygo.com/distribute/sdk#add-the-sdk-to-your-page), then call `howdygo.control(demoId)` after the SDK has initialized to get a controller for a specific demo. The initial loading snippet queues calls but cannot return a controller.

```javascript
const demo = howdygo.control("your-demo-id");
demo.next();
demo.pauseAutoProgress();
```

An explicit demo ID lets the controller queue commands while that demo's iframe is still loading. If exactly one demo has already registered, you can call `control()` without an ID and the SDK resolves it for you.

```javascript
howdygo.control().next();
```

With no registered demo, or more than one, `control()` without an ID cannot choose a target. Pass the demo ID when your page has several demos or when registering one later.

## Navigation

Move through steps and chapters.

| Method                   | What it does                                                         |
| ------------------------ | -------------------------------------------------------------------- |
| `next()`                 | Advance to the next step.                                            |
| `previous()`             | Go back to the previous step.                                        |
| `restart()`              | Restart the demo from the beginning.                                 |
| `goToStep(indexOrId)`    | Jump to a step by 1-based index or step ID.                          |
| `goToChapter(indexOrId)` | Jump to the first step of a chapter, by 1-based index or chapter ID. |

```javascript
const demo = howdygo.control("your-demo-id");

demo.next();
demo.goToStep(3); // 3rd step
demo.goToStep("step_abc123"); // by ID
demo.goToChapter(2); // 2nd chapter
```

> [!WARNING]
> `goToStep` and `goToChapter` use **1-based indices**, so the first step is
> `1`, not `0`.

## Auto-progress

Toggle the auto-progress timer that advances the demo automatically. See [Auto-Progress & Looping](https://docs.howdygo.com/create/auto-progress) for the editor settings that control this.

```javascript
demo.pauseAutoProgress(); // pause auto-progress on the current step
demo.resumeAutoProgress(); // resume auto-progress
```

Both methods only act on demos where the publisher has enabled auto-progress in the editor. To check before calling, read `autoProgress` from `getState()`.

## Reading state

Call `getState()` to read the player's current state. It returns a Promise.

```javascript
const state = await howdygo.control("your-demo-id").getState();

console.log(state.currentStepIndex); // e.g. 3
console.log(state.autoProgress); // 'disabled' | 'playing' | 'paused'
console.log(state.steps); // [{ id, index, title }, ...]
```

The resolved value:

```typescript
{
  currentStepIndex: number; // 1-based
  steps: Array<{
    id: string;
    index: number; // 1-based
    title: string | null;
  }>;
  chapters: Array<{
    id: string;
    title: string;
    index: number; // 1-based
    stepIndex: number; // 1-based step where the chapter starts
  }>;
  autoProgress: "disabled" | "playing" | "paused";
}
```

`autoProgress` tells you whether the demo's auto-progress timer is `'playing'`, `'paused'` by the viewer or by your own `pauseAutoProgress()` call, or `'disabled'` because the publisher hasn't enabled auto-progress for the demo.

If the iframe has not registered yet, `getState()` waits for registration before sending the request. The default timeout is 5 seconds, after which the Promise rejects.

## Examples

### Custom next and previous buttons

```html
<button id="prev">Previous</button>
<button id="next">Next</button>

<script>
  const demo = howdygo.control("your-demo-id");
  document.getElementById("prev").onclick = () => demo.previous();
  document.getElementById("next").onclick = () => demo.next();
</script>
```

### Pause auto-progress when the demo scrolls out of view

This only does something when auto-progress is enabled on the demo. If it's not, both calls are silent no-ops.

```javascript
const demo = howdygo.control("your-demo-id");
const iframe = document.querySelector("iframe");

const observer = new IntersectionObserver(([entry]) => {
  if (entry.isIntersecting) {
    demo.resumeAutoProgress();
  } else {
    demo.pauseAutoProgress();
  }
});

observer.observe(iframe);
```
