Sports scores
# Talmyric Server Media Import — FAQ
For release **1.1.5**.
## Getting started
### What does this add-on do?
It imports images and videos from a server folder into XenForo Media Gallery. Upload your originals through FTP/SFTP, choose the folder and gallery category in the Admin CP, review the preview, then run the batch.
### Which versions does it support?
The package requires XenForo **2.3.13 or later** and XFMG **2.3.13 or later**. The code has been checked against 2.3.13. Later versions are not blocked by those minimum requirements, but compatibility still needs testing, especially for major upgrades. Earlier versions are blocked.
### Will it work on shared hosting or a dedicated server?
Either can work if PHP can read the import folder and the server meets XenForo/XFMG requirements. Hosting storage quotas, filesystem restrictions and time limits still apply. Video conversion also needs working native XFMG video processing. For large files, CLI access is useful.
### Where is “Upload from server”?
It is an **Admin CP** navigation item. It does not appear beside the public gallery's Add media button. The administrator needs both the existing media gallery administrative permission and **Import server media** under **Groups & permissions → Administrators**.
### Where are the settings?
Open **Admin CP → Setup → Options → Talmyric Server Import**. If the group is missing, confirm the add-on installation or upgrade completed successfully.
## Folders and files
### What should I enter for the allowed import root?
Enter the full filesystem path to a dedicated folder, such as `/home/account/media-inbox` or `C:\media-inbox`. The folder must exist, be readable by PHP, and be outside the XenForo installation. Prefer a location outside the public web root.
An FTP path such as `/public_html/media-inbox` may be relative to the FTP account rather than the real filesystem root. Use your hosting file manager's full path or ask your host for it.
### What goes in “Folder relative to allowed root”?
Enter only the child folder, such as `events/october`. Leave it empty to scan the configured root. Do not enter another absolute path or use `..` to leave the root.
### Are subfolders included?
Only when **Include subfolders** is enabled in the add-on settings. Nested CSV filenames must include their relative folder path.
### Can I import any file format?
The importer is for images and videos supported by the installed XFMG configuration. It applies its own file checks and native gallery validation. A recognized extension does not guarantee valid content. Audio and executable files are outside its supported types.
### Why is a recently uploaded file rejected?
The importer protects against reading unfinished transfers. Finish FTP uploads and wait at least 60 seconds before processing. A file that changes after scanning may require a new batch.
### Are original files removed after import?
No. The add-on does not delete, move or rename your FTP originals. Remove them yourself only after checking the imported media and completed video conversions.
## Titles, descriptions and CSV
### Do I have to use CSV?
No. Choose a category, title pattern and shared description to import without CSV. Administrators can disable optional CSV metadata globally.
### How do I get a CSV template?
Use **Download blank CSV** for the column headers, or select a folder and category and click **Download folder CSV** to fill in filenames. Downloading does not create a batch or import media.
Complete the file, save as **CSV UTF-8 (comma delimited)**, enable **Use CSV titles, descriptions and tags for this batch**, select the file and click **Scan and preview**. Confirm only after reviewing the matches.
### Which CSV columns are required?
Only `filename` is required. Optional columns are `title`, `description` and `tags`. Keep headers exactly as shown. Uploads must be no larger than 5 MiB and contain no more than 100,000 data rows; folder-entry limits also apply. A blank template needs at least one filename row before upload.
### Why do downloaded filenames start with `./`?
It keeps filenames from being interpreted as spreadsheet formulas. Leave the prefix in place; the importer removes it when matching files. Filenames must include extensions and remain relative to the selected folder. Matching is case-insensitive on Windows and case-sensitive on other systems.
### How do title patterns work?
The shared pattern supports `{filename}` for the name without its extension and `{n}` for the unique file record number. A blank CSV title uses this pattern. A nonblank CSV title is literal text; tokens inside it are not expanded.
### What happens if a CSV description is blank?
**A blank description cell clears the description for that matching file.** Remove the entire `description` column to use the shared batch description instead. Files with no matching CSV row use the batch defaults.
### Can descriptions contain commas or multiple lines?
Yes. Use a spreadsheet application that saves correctly quoted UTF-8 CSV. Commas and line breaks within a cell must remain inside a quoted CSV field. The same applies to comma-separated tags in one cell.
### Why do I get “CSV tags require permission to edit gallery tags in this category”?
XFMG requires content tagging to be enabled and the importing account to have gallery tag permissions. Enable content tagging in XenForo options and grant **Tag own media items** in the account's media gallery user-group permissions. Check **Media category permissions** for destination-specific restrictions. Existing **Tag any media items** or **Manage any tags** can also satisfy XFMG's check. Administrative import permission alone is not enough.
Leave CSV tags blank if you do not need them.
### What happens to unmatched or duplicate CSV rows?
Rows whose filenames are absent from the scan are reported and ignored. Media files without a matching row use the batch defaults. Duplicate CSV filenames block confirmation: discard the preview and upload a corrected CSV in a new batch.
### Can CSV update media that was already imported?
No. CSV supplies metadata for new imports. Identical source content is still skipped by duplicate protection even if its CSV metadata changes. Edit existing media through the gallery.
## Batches and videos
### Who owns the imported media?
The administrator who creates the batch. That account's normal gallery permissions, quotas and moderation rules apply. Batch access is restricted to its owner with the required administrative permissions.
### Can I resume after a timeout or interruption?
Yes. Open the batch, refresh its status and resume. Saved completed records are retained. Resumption is per file; it does not continue from a byte offset within a partially copied file. An interrupted file may be staged again. Avoid repeatedly starting requests while the previous request may still be processing.
For a confirmed batch, run `php cmd.php talmyric:import-run BATCH_ID` from the XenForo folder to process through CLI. Run the same command to resume.
### What is the difference between Cancel and Delete?
**Cancel** permanently stops future file selection for that batch and keeps its history. A file already processing can finish. Create a new batch if you later want to import the remaining files.
**Delete** removes the batch journal. Neither action removes imported gallery media, duplicate fingerprints or FTP originals. Videos already queued in XFMG continue independently.
### What does “Queued” mean for a video?
The file was accepted into XFMG's native video processing queue; conversion has not necessarily finished. The server must run native XFMG processing. Use **Refresh video status** to update the batch after conversion. Unknown status means the importer cannot establish the native outcome, not that conversion succeeded.
### Why is a file marked duplicate when its filename is different?
Duplicate protection compares SHA-256 content fingerprints, not just filenames. It applies across this add-on's batches and categories, including queued videos. It does not search media uploaded through other tools.
### Can I reimport a duplicate if the original gallery item was deleted?
Deleting media does not remove its saved import fingerprint. This release has no duplicate-override interface. Do not delete journal records manually to repair a native video problem; resolve the XFMG processing issue first.
## Troubleshooting and maintenance
### Why does a disk-space check stop the batch?
The detected free capacity is below the configured working-space estimate plus reserve. Free space, choose smaller files or review the settings. These checks estimate staging and processing needs; they do not reserve storage and may not reflect hosting account quotas. Unavailable capacity information is reported as a warning rather than proof that sufficient space exists.
### Where can I see or download errors?
Open the batch log. Search by filename, filter by file/video status, and download matching results or the full log as CSV. Processing exceptions may also appear in XenForo's server error log. Exported logs are reports; they are not metadata templates for reupload.
### Can failed files be retried?
Yes, after correcting the cause, use **Retry failed files**. Changed source files may need a new batch. Native video conversion failures need attention through XFMG; retrying an import does not automatically repair its native conversion queue.
### Does automatic log cleanup delete media or duplicate protection?
No. Optional retention removes eligible completed batch journals while preserving gallery media, originals and duplicate fingerprints. It is disabled by default and depends on XenForo scheduled tasks. Pending, failed, queued and unconfirmed batches are not automatically removed.
### What happens if I uninstall?
Uninstalling removes the add-on's journal tables and duplicate history. Gallery media, native video queue records and FTP originals remain. Export needed logs first. Reinstalling starts without the old duplicate history and can permit reimports.
### Where are the detailed instructions?
See [README.md](README.md) for the feature list, [INSTALLATION.md](INSTALLATION.md) for detailed operation and configuration, and [TESTING.md](TESTING.md) for verification and staging checks.
For release **1.1.5**.
## Getting started
### What does this add-on do?
It imports images and videos from a server folder into XenForo Media Gallery. Upload your originals through FTP/SFTP, choose the folder and gallery category in the Admin CP, review the preview, then run the batch.
### Which versions does it support?
The package requires XenForo **2.3.13 or later** and XFMG **2.3.13 or later**. The code has been checked against 2.3.13. Later versions are not blocked by those minimum requirements, but compatibility still needs testing, especially for major upgrades. Earlier versions are blocked.
### Will it work on shared hosting or a dedicated server?
Either can work if PHP can read the import folder and the server meets XenForo/XFMG requirements. Hosting storage quotas, filesystem restrictions and time limits still apply. Video conversion also needs working native XFMG video processing. For large files, CLI access is useful.
### Where is “Upload from server”?
It is an **Admin CP** navigation item. It does not appear beside the public gallery's Add media button. The administrator needs both the existing media gallery administrative permission and **Import server media** under **Groups & permissions → Administrators**.
### Where are the settings?
Open **Admin CP → Setup → Options → Talmyric Server Import**. If the group is missing, confirm the add-on installation or upgrade completed successfully.
## Folders and files
### What should I enter for the allowed import root?
Enter the full filesystem path to a dedicated folder, such as `/home/account/media-inbox` or `C:\media-inbox`. The folder must exist, be readable by PHP, and be outside the XenForo installation. Prefer a location outside the public web root.
An FTP path such as `/public_html/media-inbox` may be relative to the FTP account rather than the real filesystem root. Use your hosting file manager's full path or ask your host for it.
### What goes in “Folder relative to allowed root”?
Enter only the child folder, such as `events/october`. Leave it empty to scan the configured root. Do not enter another absolute path or use `..` to leave the root.
### Are subfolders included?
Only when **Include subfolders** is enabled in the add-on settings. Nested CSV filenames must include their relative folder path.
### Can I import any file format?
The importer is for images and videos supported by the installed XFMG configuration. It applies its own file checks and native gallery validation. A recognized extension does not guarantee valid content. Audio and executable files are outside its supported types.
### Why is a recently uploaded file rejected?
The importer protects against reading unfinished transfers. Finish FTP uploads and wait at least 60 seconds before processing. A file that changes after scanning may require a new batch.
### Are original files removed after import?
No. The add-on does not delete, move or rename your FTP originals. Remove them yourself only after checking the imported media and completed video conversions.
## Titles, descriptions and CSV
### Do I have to use CSV?
No. Choose a category, title pattern and shared description to import without CSV. Administrators can disable optional CSV metadata globally.
### How do I get a CSV template?
Use **Download blank CSV** for the column headers, or select a folder and category and click **Download folder CSV** to fill in filenames. Downloading does not create a batch or import media.
Complete the file, save as **CSV UTF-8 (comma delimited)**, enable **Use CSV titles, descriptions and tags for this batch**, select the file and click **Scan and preview**. Confirm only after reviewing the matches.
### Which CSV columns are required?
Only `filename` is required. Optional columns are `title`, `description` and `tags`. Keep headers exactly as shown. Uploads must be no larger than 5 MiB and contain no more than 100,000 data rows; folder-entry limits also apply. A blank template needs at least one filename row before upload.
### Why do downloaded filenames start with `./`?
It keeps filenames from being interpreted as spreadsheet formulas. Leave the prefix in place; the importer removes it when matching files. Filenames must include extensions and remain relative to the selected folder. Matching is case-insensitive on Windows and case-sensitive on other systems.
### How do title patterns work?
The shared pattern supports `{filename}` for the name without its extension and `{n}` for the unique file record number. A blank CSV title uses this pattern. A nonblank CSV title is literal text; tokens inside it are not expanded.
### What happens if a CSV description is blank?
**A blank description cell clears the description for that matching file.** Remove the entire `description` column to use the shared batch description instead. Files with no matching CSV row use the batch defaults.
### Can descriptions contain commas or multiple lines?
Yes. Use a spreadsheet application that saves correctly quoted UTF-8 CSV. Commas and line breaks within a cell must remain inside a quoted CSV field. The same applies to comma-separated tags in one cell.
### Why do I get “CSV tags require permission to edit gallery tags in this category”?
XFMG requires content tagging to be enabled and the importing account to have gallery tag permissions. Enable content tagging in XenForo options and grant **Tag own media items** in the account's media gallery user-group permissions. Check **Media category permissions** for destination-specific restrictions. Existing **Tag any media items** or **Manage any tags** can also satisfy XFMG's check. Administrative import permission alone is not enough.
Leave CSV tags blank if you do not need them.
### What happens to unmatched or duplicate CSV rows?
Rows whose filenames are absent from the scan are reported and ignored. Media files without a matching row use the batch defaults. Duplicate CSV filenames block confirmation: discard the preview and upload a corrected CSV in a new batch.
### Can CSV update media that was already imported?
No. CSV supplies metadata for new imports. Identical source content is still skipped by duplicate protection even if its CSV metadata changes. Edit existing media through the gallery.
## Batches and videos
### Who owns the imported media?
The administrator who creates the batch. That account's normal gallery permissions, quotas and moderation rules apply. Batch access is restricted to its owner with the required administrative permissions.
### Can I resume after a timeout or interruption?
Yes. Open the batch, refresh its status and resume. Saved completed records are retained. Resumption is per file; it does not continue from a byte offset within a partially copied file. An interrupted file may be staged again. Avoid repeatedly starting requests while the previous request may still be processing.
For a confirmed batch, run `php cmd.php talmyric:import-run BATCH_ID` from the XenForo folder to process through CLI. Run the same command to resume.
### What is the difference between Cancel and Delete?
**Cancel** permanently stops future file selection for that batch and keeps its history. A file already processing can finish. Create a new batch if you later want to import the remaining files.
**Delete** removes the batch journal. Neither action removes imported gallery media, duplicate fingerprints or FTP originals. Videos already queued in XFMG continue independently.
### What does “Queued” mean for a video?
The file was accepted into XFMG's native video processing queue; conversion has not necessarily finished. The server must run native XFMG processing. Use **Refresh video status** to update the batch after conversion. Unknown status means the importer cannot establish the native outcome, not that conversion succeeded.
### Why is a file marked duplicate when its filename is different?
Duplicate protection compares SHA-256 content fingerprints, not just filenames. It applies across this add-on's batches and categories, including queued videos. It does not search media uploaded through other tools.
### Can I reimport a duplicate if the original gallery item was deleted?
Deleting media does not remove its saved import fingerprint. This release has no duplicate-override interface. Do not delete journal records manually to repair a native video problem; resolve the XFMG processing issue first.
## Troubleshooting and maintenance
### Why does a disk-space check stop the batch?
The detected free capacity is below the configured working-space estimate plus reserve. Free space, choose smaller files or review the settings. These checks estimate staging and processing needs; they do not reserve storage and may not reflect hosting account quotas. Unavailable capacity information is reported as a warning rather than proof that sufficient space exists.
### Where can I see or download errors?
Open the batch log. Search by filename, filter by file/video status, and download matching results or the full log as CSV. Processing exceptions may also appear in XenForo's server error log. Exported logs are reports; they are not metadata templates for reupload.
### Can failed files be retried?
Yes, after correcting the cause, use **Retry failed files**. Changed source files may need a new batch. Native video conversion failures need attention through XFMG; retrying an import does not automatically repair its native conversion queue.
### Does automatic log cleanup delete media or duplicate protection?
No. Optional retention removes eligible completed batch journals while preserving gallery media, originals and duplicate fingerprints. It is disabled by default and depends on XenForo scheduled tasks. Pending, failed, queued and unconfirmed batches are not automatically removed.
### What happens if I uninstall?
Uninstalling removes the add-on's journal tables and duplicate history. Gallery media, native video queue records and FTP originals remain. Export needed logs first. Reinstalling starts without the old duplicate history and can permit reimports.
### Where are the detailed instructions?
See [README.md](README.md) for the feature list, [INSTALLATION.md](INSTALLATION.md) for detailed operation and configuration, and [TESTING.md](TESTING.md) for verification and staging checks.