Gdrive-sync: що це і як воно працює

Синхронізація відео, фото та плеєйблів з Google Drive — пояснення без технічних деталей.

Пояснення для всіх, хто користується результатами синхронізації, — без технічних деталей. Як влаштована черга задач пайплайна — у черга задач на MongoDB; код — backend/packages/gdrive-sync/.

Навіщо це потрібно

Команда зберігає відео, фото та плеєйбли (креативи, промо, вихідні матеріали) на спільних Google-дисках. Gdrive-sync — це система, яка автоматично:

1. помічає нові та змінені відео, фото й плеєйбли на цих дисках;
2. копіює їх у власне сховище компанії (щоб не залежати від Google Drive і мати швидкі посилання для перегляду);
3. готує зручну веб-версію кожного відео та витягує з нього кадри;
4. аналізує відео за допомогою ШІ: розбиває на сцени, описує зміст, робить матеріали придатними для смислового пошуку.

Нічого не треба запускати вручну: поклали файл на диск — за деякий час він з’являється в системі вже проаналізований.

Що синхронізується, а що ні

Синхронізується:

• відео та фото зі спільних дисків, підключених до системи;
• плеєйбли — креативи-.html, які самі є сторінкою. Один файл: усе всередині, без папки з окремими картинками й скриптами поруч (папку Google Drive віддати одним файлом не може, тож і синхронізувати її нема як);
• файл потрапляє в систему і коли його щойно додали, і коли замінили новішою версією (система помічає, що вміст змінився, і обробляє файл заново).

Не синхронізується:

• Google-документи, таблиці, презентації, ярлики — все, що не є звичайним відео-, фото- чи .html-файлом (текстові файли, PDF, архіви — теж ні);
• обкладинка відео — фото з такою самою назвою, як у відеокреатива (…_Vid_…). Воно не стає окремим файлом в обліку, бо це не самостійний креатив, а картинка до відео: система бере його як прев’ю (див. нижче);
• вміст «службових» папок зі списку винятків (наприклад, усе всередині /Resources/Plugins — встановлені плагіни й шаблони, а не наші матеріали). Такі файли система бачить і запам’ятовує (вони є в обліку зі статусом «пропущено»), але не завантажує;
• файли, більші за ліміт диска обробника, — вони позначаються як «завеликий» і чекають окремого рішення.

Як це працює — на пальцях

1. Сканер кожні кілька хвилин питає Google Drive: «що змінилось?» Нові чи змінені файли він ставить у чергу на обробку. Видалені — позначає видаленими.
2. Обробник синхронізації бере файли з черги по одному: завантажує, перевіряє цілісність, зберігає оригінал у сховище компанії. Для відео додатково робить легку веб-версію для перегляду в браузері та зберігає кілька кадрів з перших секунд.
3. Обробник аналізу проганяє кожне відео через ШІ-конвеєр: визначає межі сцен, збирає ключові кадри з початку ролика (перші секунди — «хук»), отримує від ШІ текстовий опис і категорію, готує дані для смислового пошуку. Фото та плеєйбли не аналізуються — зберігається лише оригінал.

Якщо на диску лежать два однакові файли (навіть під різними назвами чи в різних папках) — система помітить це і обробить вміст лише один раз, а обидва записи посилатимуться на той самий результат.

Обкладинки та прев’ю

Назва креатива каже, що це: Vid — відео, Stat — статика. Якщо поруч із відео лежить фото з точно такою самою назвою, система розуміє, що це намальована вручну обкладинка, і показує саме її замість автоматичного кадру. Обкладинки може й не бути — тоді прев’ю робиться з першого кадру відео, як і раніше.

Так само працює і папка задачі: якщо в задачі стоїть тип медіа VID, то будь-яке фото в її папці система вважає обкладинкою, а не окремим креативом — хай як воно назване. Це якраз про файли з назвами на кшталт hook final.jpg, які нічого про себе не кажуть. Якщо в папці VID-задачі має лежати саме статика як окремий креатив — це вже інша задача, з іншим типом медіа.

Порядок завантаження не має значення: фото можна покласти й раніше за відео — система однаково не покаже його як окремий креатив, а прив’яже до відео, щойно те з’явиться.

Але назва вирішує, чиєю саме обкладинкою стане фото. Обкладинка знаходить своє відео лише за однаковою назвою. Тож фото з назвою на кшталт hook final.jpg система вже не сплутає з креативом — але й обкладинкою конкретного відео воно не стане, і відео покаже власний перший кадр. Щоб фото спрацювало як обкладинка, назвіть його точно так само, як відео, — тобто так, як написано в списку «Planned Creatives» на сторінці задачі.

Кожен креатив отримує два зображення:

• прев’ю — маленьке й стиснуте, для сітки креативів і випадних списків (щоб галерея відкривалась швидко навіть на слабкому інтернеті);
• повноякісний кадр — та сама обкладинка (або кадр, або сама статика) у вихідній якості, придатна для завантаження в рекламний кабінет.

Замінили обкладинку на диску — система це помітить і перезробить прев’ю відео; замість вручну нічого робити не треба.

Обкладинка плеєйбла. У .html немає кадру, з якого можна взяти картинку, і власної обкладинки поруч плеєйбл теж не має: назва з WEB — це цілком нормальна назва статики, тож фото з такою назвою система вважає креативом, а не обкладинкою до чогось. Замість цього система бере ту саму картинку, яку малює сам Google Drive — те, що видно на плитці файлу в інтерфейсі Drive, — і робить з неї і повноякісну обкладинку, і прев’ю.

Drive малює цю картинку не одразу після завантаження, а за якийсь час. Якщо синхронізація встигла раніше — файл усе одно синхронізується повністю, просто поки без картинки; система сама перепитує Drive на наступних циклах і додає обкладинку, коли та з’явиться. Кілька спроб — і якщо картинки так і немає, система припиняє перепитувати (є формати, для яких Drive її не малює взагалі).

Самі плеєйбли в галереї не запускаються: система показує обкладинку, а натиснувши на неї, плеєйбл відкривається в окремій вкладці.

Статуси файлу

У кожного файлу в системі є статус — за ним видно, на якому він етапі:

Кілька важливих дрібниць:

• Тимчасові збої (наприклад, перебої мережі) система лагодить сама: повторює спробу кілька разів з паузами. failed — це вже після всіх спроб.
• Видалення з Drive не видаляє копію з нашого сховища — запис лише позначається видаленим, а сам обліковий запис зникає з бази приблизно за 30 днів.
• Якщо пропущений (skipped_by_content) файл перемістити з папки-винятку — він автоматично повернеться в чергу на обробку.

Що система знає про кожен файл

• назву, шлях на диску (наприклад OC/Promos/UA_Promo_v3.mp4), розмір, тип;
• коли файл був створений у Google Drive і коли система вперше його побачила;
• технічні параметри відео: тривалість, роздільна здатність, наявність звуку (у плеєйбла таких параметрів немає — це сторінка, а не кадр);
• результати аналізу: список сцен, ключові кадри з початку, текстовий опис від ШІ.

Як подивитись інформацію про файл

Через внутрішній API можна запитати файл за точною назвою без розширення (UA_Promo_v3, а не UA_Promo_v3.mp4; великі/малі літери мають збігатися) — у відповідь прийде його статус, посилання на перегляд (веб-версія відео, оригінал фото або сам плеєйбл) і результати аналізу. Якщо файлів з такою назвою кілька — покажеться той, що відповідає назві (для …_Vid_… це відео, а не фото), з-поміж них найновіший; поруч буде кількість дублікатів.

Часті питання

Я додав файл на диск. Коли він з’явиться в системі? Зазвичай протягом кількох хвилин він потрапляє в чергу; час до статусу done залежить від розміру файлу та довжини черги.

Я перейменував папку, і файли в ній «не помітили» змін. Чому? Google Drive не повідомляє про зміни файлів усередині перейменованої папки. Шлях кожного файлу оновиться, коли зміниться сам файл, або під час планової повної звірки. Це ж стосується переміщення папки в список винятків чи з нього.

Файл у статусі failed. Що робити? Звернутись до інженерів — вони бачать причину помилки. Після виправлення файл можна повернути в чергу.

Чому мого файлу немає взагалі? Найчастіші причини: це не відео/фото/.html (наприклад, Google-документ), файл лежить на диску, який не підключений до синхронізації, або в папці зі списку винятків (тоді він є в обліку зі статусом skipped_by_content). Ще один випадок — фото, яке система вважає обкладинкою відео, а не окремим креативом: або в його назві є …_Vid_…, або воно лежить у папці задачі з типом медіа VID. Якщо це справді статика — у назві має бути Stat, а задача має бути не VID.

Чому задача не переходить у Done? Система звіряє файли в папці задачі зі списком запланованих креативів («Planned Creatives» на сторінці задачі) і не пускає задачу в Done, поки для якоїсь із цих назв немає файлу. У повідомленні про помилку перелічені саме ті назви, яких бракує.

Найчастіші причини: файл названо не так, як у плані (зайвий пробіл, (1) у кінці, інший регістр), файл лежить у підпапці, а не в самій папці задачі, або для задачі з типом медіа VID завантажили лише обкладинку без самого відео. Щойно завантажений файл система бачить одразу — чекати наступного циклу синхронізації не потрібно.

Плеєйбл синхронізувався, а картинки в галереї немає. Що робити? Почекати. Обкладинка плеєйбла — це картинка, яку малює сам Google Drive, і малює вона її з затримкою; система перепитує сама. Якщо картинки немає й через кілька годин — відкрийте файл у Drive: якщо і Drive показує його порожньою плиткою, значить Drive цей файл не намалював, і взяти обкладинку нема звідки.

Обкладинка є на диску, а в системі показується кадр із відео. Чому? Найімовірніше назви не збігаються точно — обкладинку система знаходить лише за назвою, ідентичною назві відео (розширення не рахується). Зайвий пробіл або (1) у кінці робить це вже іншим файлом.

Дублікати займають місце двічі? Ні. Вміст зберігається один раз, скільки б копій не лежало на дисках.