# Set Description: 4 способа задать описания публикаций (https://clout.wtf/guide/ru/set-description-guide/)













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

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

***

## Включение

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

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

<img alt="Переключатель Set Description в выключенном состоянии" src="__img0" />

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

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

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

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

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

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

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

<img alt="Inline-режим Text: список описаний через ;" src="__img1" />

### Пример

```
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` (только это расширение; другие игнорируются)

<img alt="Режим TXT file: путь к .txt и ссылка Download example file" src="__img2" />

### Формат файла

* Кодировка: **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** — случайно без повторов

<img alt="Режим JSON file: путь к .json и переключатель Sequential / Random" src="__img3" />

### Формат файла

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

```
[
  { "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`

<img alt="Режим Sidecar files: пояснение, ссылка Download example и переключатель fallback" src="__img4" />

### Формат 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
```

> **Note:** Для видео `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 внутри едет автоматически.

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

| Что                   | Где                                   | Комментарий                                                             |
| --------------------- | ------------------------------------- | ----------------------------------------------------------------------- |
| **Хэштеги**           | Прямо в тексте описания               | Отдельного поля нет: `"My caption #travel #2026"`                       |
| **Упоминания @user**  | Прямо в тексте описания               | Парсер ловит pop-up подсказок при наборе                                |
| **Заголовок (Title)** | Только в JSON / sidecar, поле `title` | Для **видео игнорируется**. Для **карусели** заполняется, если непустой |
| **Музыка**            | Отдельная карточка шаблона **Music**  | Не относится к описанию, настраивается отдельно                         |
| **Несколько языков**  | Внутри текста                         | Поддерживается любой Unicode (кириллица, эмодзи)                        |

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

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

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

| Симптом                                  | Причина                                                           | Решение                                                             |
| ---------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------- |
| В TikTok загружено пустое описание       | Sidecar отсутствует, fallback = Skip                              | Положить sidecar или поменять fallback на inline / .txt / .json     |
| Один и тот же текст постится по кругу    | Inline-вариантов мало → быстро кончаются → цикл начинается заново | Добавить больше вариантов через `;` или перейти на `.txt` / `.json` |
| Заголовок не появился в карусели         | `title` пустой или поле не задано                                 | Добавить непустое `"title"` в JSON / sidecar                        |
| Заголовок не появился в видео            | Так и должно быть — у видео в TikTok нет Title                    | Перенести важный текст в `description`                              |
| WARNING «Multiple non-priority sidecars» | В подпапке карусели несколько `.json`, ни один не приоритетный    | Переименовать нужный в `content.json`                               |
| Описание обрезано                        | Больше 2200 символов                                              | Сократить или убрать «воду»                                         |
| JSON не читается                         | Битый синтаксис или не UTF-8                                      | Прогнать через JSON-валидатор, проверить кодировку                  |
| Sidecar не подхватывается на ходу        | Кэш заполняется при старте треда                                  | Перезапустить тред                                                  |

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

```
                    ┌─ Один-два варианта на все посты   → 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** (для глобальных).

## Читать в блоге

* [Как продвигать приложение в TikTok: гайд по органическим установкам](https://clout.wtf/blog/ru/promote-app-tiktok-organic/)
* [Маркетинг за $0: органический рост через TikTok для стартапов](https://clout.wtf/blog/ru/tiktok-organic-growth-startups/)