From a file to a post

What happens, in the order it happens.

1. Name the browser

   Every browser that uses flock claims a name once, so the log can say which machine made each change. Nothing can be uploaded or changed until it has one.

2. Or start from a prepared upload

   Text written elsewhere can go in with one paste, or be saved as a flock.json file in a project folder. A project folder shows in flock's sidebar within seconds; opening it fills the upload from the file, its release times included, and lists the folder's videos. Progress is kept until the upload is sent, and the file is then renamed so it is not listed again.

3. Pick the video

   Drop a file on the picker, or pick one out of a watch folder. A file in a folder on the network is referenced where it lies rather than transferred through the browser, which is how a large video is published; one in a folder on your PC is first copied to the network by the worker. One video goes to every platform unless a platform is given a cut of its own.

4. Compose, one platform at a time

   Tick the platforms this video goes to. Each has its own text: a title and a description for YouTube, a caption for TikTok, Instagram and Facebook. Templates drop reusable blocks in, and adaptation rules, replace this with that on this platform, run exactly once, at confirmation.

5. Make the per-post choices

   YouTube: the playlist (a thumbnail and paid promotion are set in YouTube Studio). Instagram and Facebook: an optional cover image. TikTok: who can view the video, whether viewers may comment, duet or stitch, and the Content Disclosure Setting. All of these are chosen on this upload, from what the account offers, with nothing preselected.

6. Schedule

   One card per platform on a calendar of the coming days, starting today. Drag it to a day and hour, type an exact time, pick a saved release pattern, or release immediately.

7. Review and confirm

   The video plays beside what each platform will receive and when. With TikTok in the upload, confirming waits until the video has been shown, as TikTok asks. The confirm button has to be pressed twice within two seconds. Nothing has left the machine before this point; on confirming, the video is stored and one release per platform is queued.

8. The worker publishes

   A worker process beside the database watches the queue. YouTube is handed the video right away and releases it itself at the slot. TikTok cannot schedule, so the worker holds the post until its slot, then reads the creator's details, uploads the file in chunks and polls TikTok until the post is live. Instagram is uploaded ahead of time and published on the minute. A Facebook reel goes to the Page up to four weeks ahead, and Facebook releases it at the slot itself. Every outcome, including a failure and its reason, is written back to the release and to the log.

9. Connecting an account

   Each platform is connected once, from the terminal, through that platform's own consent page, using a developer app you register there: a Google Cloud OAuth client for YouTube, a TikTok for Developers app for TikTok, a Meta app for Instagram and Facebook. The keys and the resulting tokens are kept in the worker's configuration file on your hardware and refreshed by the worker. Revoking access on the platform ends it.

The TikTok integration, call by call

What flock asks TikTok for, and when.

Login Kit

The authorization code flow with PKCE, requesting user.info.basic and video.publish. The refresh token is stored locally and rotated by the worker.

Before every post, and whenever the TikTok box is shown: creator info

/post/publish/creator_info/query/ returns the account's display name, the audiences it may post to, whether comments, duets and stitches are switched off in its settings, and the longest video it may post. It is read afresh each time the Post to TikTok box or the review screen is shown. The post screen offers only what this returns, refuses a video longer than the limit, and stops the post with "try again later" when TikTok says the account cannot post right now.

Posting: direct post by file

/post/publish/video/init/ with the caption, the chosen audience (a post without one is refused before this call), the interaction flags, the cover time and the disclosure toggles, and FILE_UPLOAD as the source. The file is then sent to the upload address TikTok returns, in chunks of 5 to 64 MB.

Afterwards: status

/post/publish/status/fetch/ every ten seconds until TikTok reports the post complete or failed. The outcome, and TikTok's reason if it failed, is recorded on the release.

Not used

video.upload, which sends a draft to the creator's inbox, is not requested by anything in the app. Nothing reads the account's videos, followers, statistics or messages.

Requirements

• Node 22 or newer and pnpm, for the worker and the build.
• A PocketBase instance of its own, which stores the videos and the queue and serves the app.
• A machine that stays on, a NAS for example, for the database and the worker.
• A browser on the same network. flock is not meant to be reachable from the public internet.

The code and the full setup walkthrough, portal by portal, are in the README on GitHub. flock is released under the MIT license.