tiktok-trends

2026-02-25 17:06:29 +00:00
parent b6a0a57893
commit 748619a3c9
1 changed files with 258 additions and 0 deletions
@@ -0,0 +1,258 @@
+---
+name: TikTok Trends
+description: Fetch top trending TikTok videos for a given country and generate an engagement report with optional video downloads.
+version: 2
+author: pastilhas
+tags:
+  - social-media
+  - tiktok
+  - trends
+  - apify
+  - content-analysis
+skills:
+  - Apify
+dependencies:
+  - name: tiktok-trends-script
+    description: The main script at $OFFICER_USER_ROOT/../resources/scripts/apify/tiktok-trends.ts
+    check_command: test -f "$OFFICER_USER_ROOT/../resources/scripts/apify/tiktok-trends.ts"
+    optional: false
+  - name: bun
+    description: Required to run the TypeScript script
+    check_command: bun --version
+    optional: false
+  - name: yt-dlp
+    description: Required only when download option is enabled. Downloads TikTok videos.
+    check_command: yt-dlp --version
+    optional: true
+inputs:
+  - name: country
+    description: Country code to fetch trending videos for.
+    type: select
+    default: PT
+    required: false
+    options:
+      - value: PT
+        label: Portugal
+      - value: US
+        label: United States
+      - value: BR
+        label: Brazil
+      - value: GB
+        label: United Kingdom
+      - value: ES
+        label: Spain
+      - value: FR
+        label: France
+      - value: DE
+        label: Germany
+      - value: IT
+        label: Italy
+      - value: NL
+        label: Netherlands
+      - value: BE
+        label: Belgium
+      - value: PL
+        label: Poland
+      - value: RO
+        label: Romania
+      - value: SE
+        label: Sweden
+      - value: AT
+        label: Austria
+      - value: CH
+        label: Switzerland
+      - value: IE
+        label: Ireland
+      - value: CA
+        label: Canada
+      - value: AU
+        label: Australia
+      - value: MX
+        label: Mexico
+      - value: AR
+        label: Argentina
+      - value: CO
+        label: Colombia
+      - value: CL
+        label: Chile
+      - value: JP
+        label: Japan
+      - value: KR
+        label: South Korea
+      - value: IN
+        label: India
+      - value: TR
+        label: Turkey
+      - value: SA
+        label: Saudi Arabia
+      - value: AE
+        label: United Arab Emirates
+      - value: ZA
+        label: South Africa
+      - value: NG
+        label: Nigeria
+  - name: limit
+    description: Number of trending videos to fetch (1-100).
+    type: number
+    default: 20
+    min: 1
+    max: 100
+    required: false
+  - name: download
+    description: Download video files using yt-dlp (requires yt-dlp to be installed).
+    type: boolean
+    default: false
+    required: false
+  - name: api_token
+    description: Apify API token with access to actors. Get yours at https://console.apify.com/account/integrations
+    type: string
+    required: true
+    sensitive: true
+outputs:
+  - name: engagement_report
+    description: Markdown report with trending videos analysis, engagement metrics, top hashtags, sounds, and creators.
+    path: tiktok_trends_<country>_<timestamp>/report-YYYY-MM-DD.md
+  - name: raw_data
+    description: Raw JSON data from Apify actor containing all video metadata.
+    path: tiktok_trends_<country>_<timestamp>/raw-YYYY-MM-DD.json
+  - name: execution_log
+    description: Complete script execution log with stdout and stderr for debugging.
+    path: tiktok_trends_<country>_<timestamp>/run.log
+  - name: summary
+    description: Human-readable summary of the run including cost analysis and file listing.
+    path: tiktok_trends_<country>_<timestamp>/report.md
+  - name: videos
+    description: Downloaded video files with metadata (only present if download option was enabled).
+    path: tiktok_trends_<country>_<timestamp>/videos/
+    optional: true
+config:
+  timeout: 600
+  retry_count: 0
+---
+
+# TikTok Trends
+
+Fetch top trending TikTok videos for a given country and generate a comprehensive engagement report.
+
+## Overview
+
+This task uses the Apify `novi~fast-tiktok-scraper` actor to fetch trending videos from TikTok for a specified country. It generates:
+- **Engagement metrics** (total/average views, likes, shares, comments)
+- **Top hashtags** found in trending content
+- **Popular sounds** being used
+- **Creator analysis** (who appears multiple times in trending)
+- **Complete video list** with links and stats
+
+Optionally downloads videos using yt-dlp for offline analysis.
+
+## Pre-execution Checks
+
+1. **Validate inputs**:
+   - `api_token` must be provided (required)
+   - `country` must be a valid 2-letter country code
+   - `limit` must be between 1-100
+   
+2. **Check dependencies**:
+   - Verify script exists at `$OFFICER_USER_ROOT/../resources/scripts/apify/tiktok-trends.ts`
+   - Verify bun is installed
+   - If `download=true`, verify yt-dlp is installed
+
+3. **Test Apify token**:
+   - Make a test call to `GET https://api.apify.com/v2/users/me` to validate the token
+   - Abort with clear error if token is invalid or account has no credits
+
+## Execution
+
+Run the script with the following command:
+
+```bash
+bun "$OFFICER_USER_ROOT/../resources/scripts/apify/tiktok-trends.ts" \
+  --apikey "<api_token>" \
+  --country "<country>" \
+  --limit <limit> \
+  --output "<output_dir>" \
+  <download_flag>
+```
+
+Where:
+- `<download_flag>` is `--download` if `download=true`, otherwise omitted
+- `<output_dir>` is a timestamped directory created inside `$HOME/tiktok-trends/` (the logged-in user's home directory)
+
+**Pipe output to log**:
+```bash
+<command_above> 2>&1 | tee "<output_dir>/run.log"
+```
+
+## Success Criteria
+
+The task is considered successful when:
+- Script exits with code 0
+- `report-YYYY-MM-DD.md` exists and is non-empty
+- `raw-YYYY-MM-DD.json` exists and contains valid JSON array
+- (If download enabled) `videos/` directory exists with at least one file
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Script exits non-zero | Check `run.log` for Apify/API errors. Common causes: invalid token, no credits, rate limits |
+| Empty results | Report "No trending videos found" but mark as success if files were created |
+| Partial results | Report success if at least 1 video returned, note the discrepancy |
+| Timeout (>10 min) | Kill process, report timeout. Check Apify actor status in console |
+| Download failures | Report which videos failed but mark task as success if main report generated |
+
+## Post-execution
+
+After successful execution:
+
+1. **Verify outputs**:
+   - Check all expected files exist
+   - Validate JSON is parseable
+   - If download enabled, count video files
+
+2. **Generate summary** (`report.md`):
+   ```markdown
+   # TikTok Trends Run Summary
+
+   ## Run Details
+   - **Date**: YYYY-MM-DD
+   - **Timestamp**: HH:MM:SS
+   - **Apify Actor**: novi~fast-tiktok-scraper
+   - **Country**: <country_name> (<country_code>)
+   - **Requested**: <limit> videos
+   - **Received**: <actual_count> videos
+   - **Duration**: <X> minutes <Y> seconds
+
+   ## Cost Analysis
+   - **Apify Credits Used**: <cost> USD
+   - **Cost per Video**: $<cost/actual_count>
+
+   ## Key Findings
+   - **Top Video**: @<creator> - <views> views
+     <description_preview>
+     URL: <url>
+   
+   - **Top Hashtag**: #<hashtag> (<count> occurrences)
+   - **Top Sound**: <sound_name> (<count> uses)
+
+   ## Output Files
+   - `report-YYYY-MM-DD.md` (<size>) - Engagement report
+   - `raw-YYYY-MM-DD.json` (<size>) - Raw API data
+   - `run.log` (<size>) - Execution log
+   - `videos/` (<count> files, <total_size>) - Downloaded videos (if enabled)
+
+   ## Notes
+   - <any_warnings_or_errors_from_log>
+   ```
+
+3. **Cleanup**:
+   - Remove temporary files if any
+   - Report final status to user
+
+## Notes
+
+- **Rate limiting**: The Apify actor may take 1-3 minutes depending on the limit
+- **Costs**: Each run uses Apify compute units. Monitor usage at https://console.apify.com/billing
+- **Data freshness**: Trends data is near real-time but may have slight delays
+- **Video downloads**: Downloading many videos can take significant time and storage
+- **Country availability**: Not all countries have sufficient trending data; some may return fewer results than requested