> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pikselsystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Frequently asked questions about Piksel

> Answers to the most common questions about screens, media, playlists, schedules, smart rules, and team access in Piksel.

Whether you're setting up your first screen or managing a large deployment, you may run into questions that other Piksel users have faced before. The answers below are based on how the platform actually works, so you can resolve issues quickly and get back to managing your content.

<AccordionGroup>
  <Accordion title="Why is my screen showing as offline?">
    Piksel marks a screen as offline when it has not received a heartbeat from the device in approximately two minutes. The Apple TV app sends a heartbeat to `POST /api/player/displays/{display_id}/heartbeat` at regular intervals. If that signal stops reaching the server — due to a network interruption, the app being closed, or the device going to sleep — the platform detects the gap and updates the screen's status to offline.

    If you have offline alerts enabled in your notification preferences, Piksel also sends you an email at the moment the screen is marked offline.

    Once the device reconnects and heartbeats resume, the screen status returns to online automatically — no manual action is required.
  </Accordion>

  <Accordion title="My pairing code isn't working — what should I check?">
    Pairing requires a valid 6-digit code generated by the Piksel app on your Apple TV, and the display must still be in an unpaired state. Check the following:

    * **Code accuracy** — confirm you are entering the exact 6-digit code shown on the Apple TV screen. Codes are case-insensitive but must be digit-exact.
    * **Unpaired status** — a code only works if the display has not yet been claimed. If the device was previously paired to another account, it must be reset and a new code generated before you can pair it again.
    * **Code freshness** — if the Apple TV app was restarted, it generates a new code. Use the code currently displayed on the screen.

    If the issue persists, restart the Piksel app on the Apple TV to generate a fresh code, then try pairing again from the dashboard.
  </Accordion>

  <Accordion title="Can I delete media that's in a playlist?">
    Yes. When you delete a media item, Piksel automatically removes it from every playlist that references it — there is no need to manually clean up playlists first. The media is cleanly removed from all playlists.

    Keep in mind that if a screen is actively playing a playlist that contained the deleted media, that slot will no longer appear the next time the playlist is loaded.
  </Accordion>

  <Accordion title="What happens when I delete a playlist?">
    Deleting a playlist triggers three automatic actions:

    1. **Screens are unassigned** — any screen that had this playlist set as its default will no longer have a default playlist assigned.
    2. **Schedules are deleted** — all schedules that reference the playlist are permanently removed.
    3. **Playlist items are removed** — the items within the playlist are deleted along with it.

    <Warning>
      Deleting a playlist cannot be undone. Screens that relied on it as their default or through a schedule will have no content to play until you assign a new playlist.
    </Warning>
  </Accordion>

  <Accordion title="Why isn't my smart rule triggering?">
    Smart rules rely on weather data to evaluate their conditions, and weather data requires a location. Check the following:

    * **Location coordinates are set** — open the screen's detail page and confirm that a location (latitude and longitude) has been configured in the weather coordinates field. Without a location, the weather engine has no data to evaluate, and the rule will never trigger.
    * **Condition type and value** — verify that the condition you defined (for example, temperature above a threshold, or a specific weather condition) matches what is actually being reported for that location.
    * **Evaluation timing** — smart rules are evaluated automatically approximately every five minutes. If you just saved a rule, wait a few minutes before expecting it to trigger.

    You can also manually trigger an evaluation from the Smart Rules page in the dashboard without waiting for the next automatic cycle.
  </Accordion>

  <Accordion title="How do schedules and smart rules interact?">
    Piksel uses a clear priority order to decide what plays on a screen at any given moment:

    1. **Smart Rule** — if an active smart rule matches the current weather conditions for the screen's location, it overrides everything else and plays the playlist defined in that rule.
    2. **Schedule** — if no smart rule is active, Piksel checks for a scheduled playlist that is currently within its active time window and day-of-week settings.
    3. **Default playlist** — if neither a smart rule nor a schedule applies, the screen falls back to its directly assigned default playlist.

    <Tip>
      Use smart rules for condition-based overrides (such as weather events), schedules for time-based programming, and the default playlist as your always-on fallback.
    </Tip>
  </Accordion>

  <Accordion title="Can I assign one playlist to multiple screens?">
    Yes. A single playlist can be assigned as the default playlist to as many screens as you like. Multiple displays can reference the same `current_playlist_id`, and they will all play the same content. Similarly, you can create schedules that assign the same playlist to different screens at different times.
  </Accordion>

  <Accordion title="How often are smart rules evaluated?">
    Smart rules are evaluated automatically every approximately five minutes. The scheduler fetches current weather data for each screen's configured location and checks whether any rule conditions are met.

    You can also trigger an immediate evaluation at any time from the Smart Rules page in the dashboard. This is useful when testing a newly created rule or when you want to force a condition check outside the regular cycle.
  </Accordion>

  <Accordion title="What media types are supported?">
    Piksel supports three types of media:

    * **Images** — standard image files that you upload directly to the media library.
    * **Videos** — video files uploaded to the media library; you can optionally include a thumbnail image during upload.
    * **YouTube videos** — imported by URL. Piksel stores the embed URL and thumbnail automatically; the video plays via the YouTube embed player on the screen.

    When browsing your media library, you can filter by type to view only images, videos, or YouTube imports.
  </Accordion>

  <Accordion title="Can team members see all branches?">
    No. A team member's access is scoped to the specific branches assigned to them when they were invited. They can only see and manage screens, media, playlists, and schedules that belong to their assigned branches. If a team member reports missing content, check their branch access in the Team settings and add the relevant branches as needed.
  </Accordion>
</AccordionGroup>