# Play Folder
This function block plays images from a selected folder, returning one file per evaluation. Use it to step through image datasets, preview sequences, or feed images into downstream processing. You can choose a default folder with the folder selector button, override it via the `Folder Path` input, filter files with a glob pattern, and control playback with Mode and Order controls.
## π₯ Inputs
`Folder Path` Optional string input that overrides the default folder selected by the folder button. Provide a full folder path to change the source at runtime.
`Restart` Optional boolean input. When True, the block resets playback for the current Mode and returns the reset (edge) image on that evaluation.
Notes: These are input sockets.
## π€ Outputs
`Image` The current image file read from the folder. This is an image output socket.
`File Path` Absolute path of the current image file. This is a string output socket.
`Restarted` Boolean that is True when the block returned a wrapped or reset edge image on this evaluation. This is an output socket.
Notes: These are output sockets.
## πΉοΈ Controls
`Select folder` Button to choose the default folder used when `Folder Path` is empty.
`Glob pattern` Text field to filter files using Python glob syntax (examples: `*`, `*.png`, `**/*`).
`Mode` Dropdown to control playback direction: `Forward`, `Backward`, or `Stop`.
`Order` Dropdown to select file ordering: `Name` (natural filename sort) or `Time` (file modification time).
Notes: These are visible widgets that affect how the block selects and returns files.
## π¨ Features
* Playlist management: builds and caches a list of image files matching the chosen folder, glob pattern, and order.
* Flexible playback: supports forward, backward, and stopped modes with wrap-around behavior.
* Folder override: runtime override via `Folder Path` input without changing the saved default.
* Restart handling: explicit `Restart` input resets playback and returns the edge image on that evaluation.
* File metadata output: returns the absolute path for easy logging or downstream processing.
* Optional asynchronous frame upload: if available, frames can be uploaded in the background for remote logging.
## βοΈ Running mechanism
On each evaluation the block determines the effective folder (default or overridden), checks the glob pattern and order, and refreshes its internal playlist when needed. It tracks the current index and returns the image at that index along with its file path and a `Restarted` flag. After returning the current image, the block prepares the next index according to the selected `Mode` (forward/backward/stop), wrapping to the start or end when necessary.
## π Usage instructions
1. Click the `Select folder` button to choose a default folder, or leave it empty and provide a path at runtime through the `Folder Path` input.
2. Enter a `Glob pattern` to filter files (use `*` for everything or `*.jpg` / `**/*.png` for specific types).
3. Choose `Mode` to advance, step back, or hold the current image between evaluations.
4. Choose `Order` to sort files by name or modification time.
5. Optionally send `Restart` = True to reset playback to the current modeβs edge image.
## π‘ Tips and Tricks
* Preview images in a larger window by sending the `Image` output into the `Show Image` block for interactive viewing while stepping through the folder.
* Save interesting frames using `Image Write` or batch-export examples with `Image Logger` connected to the `Image` output.
* If images are too large for downstream AI blocks, connect `Image Resize` or `Image Resizer` after the `Image` output to reduce processing time.
* To focus on a specific area of each image before analysis, stitch `Image ROI Select` (or `Image ROI`) after this block and feed the cropped result into detectors like `Find Object` or `Mask Detection`.
* For visual reports or combined views, collect multiple frames and pass them to `Collage Images` or `Image Concatenate`.
* When building dataset-driven workflows, use `File Path` output to create logs or CSVs alongside the image data using data export blocks.
(hint: only combine with the listed function blocks available in the environment.)
## π οΈ Troubleshooting
* No files found: Check that the selected folder contains supported image extensions and that the `Glob pattern` matches your filenames.
* Invalid folder override: Ensure the `Folder Path` input is a non-empty string and points to an existing directory.
* Unexpected order: Use `Order` = `Time` to sort by modification timestamp; use `Name` for predictable filename ordering (natural sort handles numeric parts).
* Playback not advancing: Verify the `Mode` setting is not `Stop` and that the block receives evaluations (some run modes run only when the scenario executes).
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.augelab.com/function-blocks/input-output/image-inputs/play-folder.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.