Set Description: 4 способа задать описания публикаций

Описание (caption) — это текст, который публикуется вместе с видео или каруселью в TikTok. В Clout Uploader его источник настраивается в шаблоне через переключатель Set Description и выбор одного из четырёх источников: Inline text, Text file (.txt), JSON file или Sidecar files.

В этом гайде разберём все четыре варианта: когда использовать какой, в каком формате готовить файлы, как приложение выбирает варианты и что делать, если что-то идёт не так.

Включение

В шаблоне есть переключатель Set Description:

• Выключен → приложение оставит поле описания в TikTok пустым.
• Включён → нужно выбрать источник описания.

После включения появляется выбор из четырёх источников: Text, TXT file, JSON file, Sidecar files. Дальше — про каждый по отдельности.

📦 Готовые шаблоны-примеры скачиваются прямо из приложения: на странице шаблонов рядом с каждым полем есть ссылка «Download example». Файлы лежат в webapp/static/examples/:

• descriptions.example.txt
• content.example.json
• sidecar.example.json

Способ 1. Inline text — несколько описаний через ;

Когда использовать

Когда у тебя несколько коротких описаний и не хочется создавать отдельный файл.

Что задавать в UI

• Источник → Text
• Поле Descriptions — все варианты в одну строку, разделённые точкой с запятой ;

Пример

First caption #tag1; Second caption with emoji 🎬; Third caption @mention #hot

Как выбирается

Случайно без повторов: приложение крутит варианты случайным образом, помечая каждый как использованный. Когда все варианты закончились — цикл начинается заново.

Подводные камни

• Если в самом тексте есть ; — он будет восприниматься как разделитель. Перенеси описание во внешний .txt или sidecar.
• Пустые блоки между ;; игнорируются.

Способ 2. Text file — .txt, по одному описанию на строку

Когда использовать

Когда у тебя 10+ описаний и удобнее хранить их во внешнем файле, который можно править в любом текстовом редакторе.

Что задавать в UI

• Источник → TXT file
• Поле Descriptions file (.txt) — абсолютный путь к .txt (только это расширение; другие игнорируются)

Формат файла

• Кодировка: UTF-8 (BOM поддерживается)
• Перенос строк: LF или CRLF — оба ок (нормализуются)
• Одна строка = одно описание
• Пустые строки игнорируются
• Хэштеги и эмодзи пишутся прямо в строку — отдельных полей нет

Пример (descriptions.example.txt)

Put your caption here — replace this line with your own text
Add hashtags inline like this #example #replace_me
Emojis work too 🎬 — drop them anywhere in the caption
Each line in this file becomes one TikTok caption
Empty lines are ignored, max 2200 characters per caption

Как выбирается

Случайно без повторов — так же, как у inline text.

Подводные камни

• Расширение должно быть только .txt. .text, .md, .csv не подойдут.
• Не используй # для комментариев — строка с # пойдёт в TikTok как описание с хэштегом.

Способ 3. JSON file — {title, description} для каждой публикации

Когда использовать

• Когда у каруселей нужны отдельные заголовки (поле Title в TikTok).
• Когда нужен последовательный порядок (а не только случайный).
• Когда хочется хранить контент в структурированном виде (для скриптов, генераторов, AI-пайплайнов).

Что задавать в UI

• Источник → JSON file
• Поле Title+Description file (.json) — абсолютный путь к .json
• Поле Selection order:
  • Sequential — элементы используются по порядку: первый, второй, третий…
  • Random — случайно без повторов

Формат файла

Корень — массив, каждый элемент — объект с двумя полями:

[
  { "title": "...", "description": "..." },
  { "title": "...", "description": "..." }
]

Поля:

• description — обязательный текст описания (≤ 2200 символов).
• title — опциональный.
  • Для видео в TikTok заголовков нет — поле title игнорируется.
  • Для карусели заголовок заполняется, если он непустой. Если title: "" или поле отсутствует — поле Title в TikTok не трогается.
• Любые другие ключи (например _comment) парсер игнорирует — можно держать комментарии прямо в файле.

Пример (content.example.json)

[
  {
    "_comment": "Этот ключ игнорируется парсером",
    "title": "Put your title here",
    "description": "Put your description here — replace this with your TikTok caption #hashtag"
  },
  {
    "title": "",
    "description": "Leave title empty if you don't want one — only the description will be set"
  },
  {
    "title": "Add hashtags inline",
    "description": "Hashtags go inside the description, not a separate field 🎯 #example #replace"
  },
  {
    "title": "Emojis work fine",
    "description": "Emojis 🎬 ✨ 🚀 are supported in both title and description"
  }
]

Подводные камни

• JSON должен быть валидным. Любая ошибка синтаксиса — и приложение откатится на legacy-источник (txt-файл или inline-текст, если они заданы).
• Пустой массив [] → описаний нет → откат на legacy.
• Кодировка строго UTF-8.

Способ 4. Sidecar — отдельный .json рядом с каждым медиа

Когда использовать

• Когда каждое видео или карусель имеет своё уникальное описание, и важна жёсткая привязка «этот текст — к этому файлу».
• Когда контент готовится в пайплайне (генератор / редактор), который кладёт описание в отдельный файл рядом с медиа.
• В Seeding-режиме, чтобы не путать, какое описание к какому ролику.

Что задавать в UI

• Источник → Sidecar files
• Поле If sidecar is missing — что делать, если у конкретного файла нет своего sidecar:
  • Skip description (по умолчанию) — оставить поле в TikTok пустым
  • Use inline text — взять из глобального поля Descriptions
  • Use global .txt — взять из глобального .txt
  • Use global .json — взять из глобального .json

Формат sidecar-файла

Объект с двумя полями (рекомендуемая форма):

{
  "title": "Put your title here",
  "description": "Put your description here — replace this with your TikTok caption #hashtag"
}

Поддерживается также форма «массив» (для совместимости — берётся первый элемент):

[
  {"title": "...", "description": "..."}
]

Куда класть sidecar

Видео

Файл <имя_видео>.json в той же папке рядом с видео:

videos/
├── clip_1.mp4
├── clip_1.json          ← описание для clip_1.mp4
├── clip_2.mov
├── clip_2.json          ← описание для clip_2.mov
└── clip_3.mp4           ← у этого нет sidecar — сработает fallback

Для видео title всегда игнорируется — TikTok не показывает заголовок у видео.

Карусель — режим подпапок (поддерживается)

Sidecar лежит внутри подпапки карусели. Имя выбирается по приоритету (без учёта регистра):

1. content.json
2. description.json
3. caption.json
4. Любой первый *.json (естественная сортировка)

carousels/
├── 01_summer/
│   ├── 1.jpg
│   ├── 2.jpg
│   ├── 3.jpg
│   └── content.json          ← приоритет 1
├── 02_promo/
│   ├── photo_a.png
│   ├── photo_b.png
│   └── description.json      ← приоритет 2
└── 03_lifestyle/
    ├── img1.png
    └── caption.json          ← приоритет 3

Если в подпапке несколько .json-файлов, ни один из которых не входит в приоритетный список, в логи запишется WARNING и возьмётся первый по сортировке. Не плоди двусмысленность — назови файл одним из приоритетных имён.

Карусель — плоский режим (НЕ поддерживается)

Sidecar в плоском режиме каруселей не работает — нет однозначной привязки фото к группе. Если нужны индивидуальные описания → переходи на режим подпапок.

Пример sidecar-файла (sidecar.example.json)

{
  "_comment": "Save next to your media. For a VIDEO: rename to .json (e.g. clip1.mp4 → clip1.json) in the same folder. For a CAROUSEL: rename to content.json (or description.json / caption.json) and put it INSIDE the carousel subfolder. 'title' is optional and ignored for videos. 'description' is capped at 2200 chars. The _comment key is ignored by the parser.",
  "title": "Put your title here",
  "description": "Put your description here — replace this with your TikTok caption #hashtag"
}

Что происходит с sidecar после публикации

• Видео: <имя>.json перемещается в used/ (или удаляется) вместе с видео, синхронно.
• Карусель в подпапках: вся подпапка переезжает в used/ целиком — sidecar внутри едет автоматически.

Хэштеги, упоминания, заголовки, музыка — где задавать

Лимиты и нормализация

• Максимум 2200 символов на описание (хард-кап TikTok).
• Если описание длиннее — приложение обрежет до 2200 и запишет WARNING в лог.
• BOM () в начале файла обрезается автоматически.
• Переносы строк нормализуются (\r\n → \n, \r → \n).
• Пробелы в начале и конце удаляются.

Что делать, если что-то идёт не так

Шпаргалка: какой источник выбрать

                    ┌─ Один-два варианта на все посты   → Inline text
                    │
описания одинаковые ├─ 10+ простых описаний без заголовков  → Text file (.txt)
для всех роликов ───┤
                    └─ Нужны заголовки, нужен Sequential   → JSON file


описание уникальное ──→ Sidecar (видео: <name>.json,
для каждого                          карусель: content.json в подпапке)
файла

Где скачать шаблоны-примеры

В приложении на странице шаблонов рядом с каждым полем есть ссылка «Download example». Они также лежат в репозитории:

• webapp/static/examples/descriptions.example.txt — пример .txt
• webapp/static/examples/content.example.json — пример глобального .json
• webapp/static/examples/sidecar.example.json — пример sidecar

Бери файл, заменяй текст внутри на свой и сохраняй рядом с медиа (для sidecar) или указывай путь к нему в поле Title+Description file / Descriptions file (для глобальных).