appydave-tools 0.15.0 → 0.16.0

data/docs/tools/youtube-manager.md

@@ -0,0 +1,248 @@
+# YouTube Manager
+
+Retrieve and update YouTube video metadata, descriptions, tags, and other details at scale.
+
+## What It Does
+
+**YouTube Manager** automates YouTube video metadata management. Instead of manually clicking through YouTube Studio, this tool:
+
+- Retrieves video metadata (title, description, tags, category)
+- Updates descriptions, titles, tags across multiple videos
+- Fetches caption/subtitle information
+- Handles YouTube API authentication
+- Generates detailed video reports
+- Supports batch operations for efficiency
+
+## How to Use
+
+### Authentication Setup
+
+First time only - authenticate with Google:
+
+```bash
+youtube_manager get -v dQw4w9WgXcQ
+```
+
+This opens a browser to authorize the app with your YouTube account. The token is stored locally in `~/.config/appydave`.
+
+### Get Video Details
+
+```bash
+# Get information about a specific video
+youtube_manager get -v dQw4w9WgXcQ
+
+# Output shows: title, description, tags, category, view count, etc.
+```
+
+### Update Video Metadata
+
+```bash
+# Update title
+youtube_manager update -v dQw4w9WgXcQ -t "New Video Title"
+
+# Update description
+youtube_manager update -v dQw4w9WgXcQ -d "New description here..."
+
+# Update tags (comma-separated)
+youtube_manager update -v dQw4w9WgXcQ -g "tag1,tag2,tag3"
+
+# Update category (use category ID)
+youtube_manager update -v dQw4w9WgXcQ -c "15"
+
+# Combine multiple updates
+youtube_manager update -v dQw4w9WgXcQ -t "New Title" -d "New desc" -g "tag1,tag2"
+```
+
+### Common YouTube Category IDs
+
+| ID | Category |
+|----|----------|
+| 1 | Film & Animation |
+| 2 | Autos & Vehicles |
+| 10 | Music |
+| 15 | Pets & Animals |
+| 17 | Sports |
+| 18 | Shorts |
+| 19 | Travel & Events |
+| 20 | Gaming |
+| 21 | Videoblogging |
+| 22 | People & Blogs |
+| 23 | Comedy |
+| 24 | Entertainment |
+| 25 | News & Politics |
+| 26 | Howto & Style |
+| 27 | Education |
+| 28 | Science & Technology |
+| 29 | Nonprofits & Activism |
+
+## Use Cases for AI Agents
+
+### 1. Post-Rebrand Updates
+```bash
+# Change channel name in all video descriptions (scenario)
+# AI agent: Get all videos, identify descriptions containing old name
+# Then update each with new branding
+youtube_manager get -v VIDEO_ID_1
+youtube_manager update -v VIDEO_ID_1 -d "Updated description with new brand name"
+```
+**AI discovers**: Current naming patterns, branding consistency. Can identify all rebranding opportunities and execute bulk updates.
+
+### 2. Tag Standardization
+```bash
+# Ensure consistent tagging across catalog
+youtube_manager get -v VIDEO_ID_1  # Get current tags
+# AI analyzes tag patterns, suggests standardized tags
+youtube_manager update -v VIDEO_ID_1 -g "correct,standardized,tags"
+```
+**AI discovers**: Tagging patterns, missing tags, inconsistent naming. Can standardize tags across entire catalog.
+
+### 3. Category Auditing & Correction
+```bash
+# Get videos in wrong category
+youtube_manager get -v VIDEO_ID_1  # Check category
+# AI identifies misclassified videos
+youtube_manager update -v VIDEO_ID_1 -c "15"  # Move to correct category
+```
+**AI discovers**: Category assignments, whether videos are properly categorized. Can suggest corrections based on content.
+
+### 4. Metadata Extraction for Analytics
+```bash
+# Get video details for export
+youtube_manager get -v VIDEO_ID_1
+# AI collects metadata across multiple videos for analysis
+```
+**AI discovers**: View counts, engagement metrics, description patterns. Can generate reports, identify top performers.
+
+### 5. Description Optimization
+```bash
+# Get current description
+youtube_manager get -v VIDEO_ID_1
+# AI analyzes description for SEO, engagement, clarity
+# Suggests improvements including keywords, CTAs, timestamps
+youtube_manager update -v VIDEO_ID_1 -d "Optimized description with keywords and structure"
+```
+**AI discovers**: Current SEO elements, call-to-actions, structure. Can improve descriptions for discoverability and engagement.
+
+### 6. Series/Playlist Linking
+```bash
+# Get videos, identify series
+youtube_manager get -v VIDEO_ID_1
+# AI analyzes which videos belong to series
+# Suggests adding series links to descriptions
+youtube_manager update -v VIDEO_ID_1 -d "Optimized with series link in description"
+```
+**AI discovers**: Video relationships, series structure. Can add linking information to improve viewer navigation.
+
+### 7. Bulk Correction Workflows
+```bash
+# Scenario: Need to update 50 videos with new info
+# AI agent orchestrates:
+# 1. Get all video IDs in channel
+# 2. For each: get metadata, analyze, suggest updates
+# 3. Batch execute updates with youtube_manager
+```
+**AI discovers**: What needs changing, patterns across videos. Can execute systematic bulk corrections.
+
+### 8. Caption/Subtitle Management (Future)
+```bash
+# Plan AI workflow: get video captions, analyze, update
+youtube_manager get -v VIDEO_ID_1
+# Returns caption information when available
+```
+**AI discovers**: Whether videos have captions, language availability. Can plan caption addition or updates.
+
+### 9. Content Audit & Compliance
+```bash
+# Get descriptions to audit for compliance
+youtube_manager get -v VIDEO_ID_1
+# AI reviews descriptions for brand compliance, accuracy, links
+# Suggests corrections for non-compliant videos
+```
+**AI discovers**: Compliance issues, outdated links, inaccurate info. Can flag and correct systematically.
+
+### 10. Performance Metadata Analysis
+```bash
+# Get metrics alongside descriptions
+youtube_manager get -v VIDEO_ID_1
+# AI correlates description length, tags, category with performance
+# Suggests improvements based on high-performing patterns
+```
+**AI discovers**: What metadata correlates with views/engagement. Can recommend optimizations based on data patterns.
+
+## Command Reference
+
+### Get Command
+```bash
+youtube_manager get -v VIDEO_ID [options]
+```
+
+| Option | Short | Long | Description |
+|--------|-------|------|-------------|
+| Video ID | `-v` | `--video-id ID` | YouTube Video ID (required) |
+| Help | `-h` | `--help` | Show help message |
+
+**Output includes**: Title, description, tags, category, view count, like count, upload date.
+
+### Update Command
+```bash
+youtube_manager update -v VIDEO_ID [options]
+```
+
+| Option | Short | Long | Description |
+|--------|-------|------|-------------|
+| Video ID | `-v` | `--video-id ID` | YouTube Video ID (required) |
+| Title | `-t` | `--title TITLE` | New video title |
+| Description | `-d` | `--description DESC` | New description |
+| Tags | `-g` | `--tags TAGS` | Comma-separated tags |
+| Category | `-c` | `--category-id ID` | YouTube category ID |
+| Help | `-h` | `--help` | Show help message |
+
+## Finding Video IDs
+
+Video ID is the part after `v=` in YouTube URLs:
+
+```
+https://www.youtube.com/watch?v=dQw4w9WgXcQ
+                               ^^^^^^^^^^^^^^ <- This is the video ID
+```
+
+Or after `youtu.be/`:
+
+```
+https://youtu.be/dQw4w9WgXcQ
+         ^^^^^^^^^^^^^^ <- This is the video ID
+```
+
+## Configuration
+
+YouTube Manager uses Google OAuth 2.0 for authentication:
+
+- **Config location**: `~/.config/appydave/channels.json`
+- **Token storage**: `~/.config/appydave/` (auto-created on first auth)
+- **No manual setup needed**: First command triggers authentication flow
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Authentication failed" | Delete `~/.config/appydave` and run command again to re-authenticate |
+| "Invalid video ID" | Verify video ID is correct (check YouTube URL) |
+| "Permission denied" | Re-authenticate with account that owns the channel |
+| "API quota exceeded" | Wait 24 hours or upgrade YouTube API quota in Google Cloud Console |
+
+## Tips & Tricks
+
+1. **Batch operations**: Create shell script to update multiple videos
+2. **Descriptions with newlines**: Use proper escaping for multi-line descriptions
+3. **Tag limits**: YouTube allows max 500 characters of tags total
+4. **Description limits**: Max 5000 characters for descriptions
+5. **Test first**: Use `get` to verify video before using `update`
+
+---
+
+**Related Tools**:
+- `gpt_context` - Gather context before planning metadata updates
+- `youtube_automation` - Automate repetitive YouTube workflows
+- `configuration` - Manage multiple YouTube channels
+
+**References**: [YouTube Data API](https://developers.google.com/youtube/v3)

data/lib/appydave/tools/{subtitle_manager → subtitle_processor}/clean.rb

@@ -2,7 +2,7 @@
 
 module Appydave
   module Tools
-    module SubtitleMaster
+    module SubtitleProcessor
       # Clean and normalize subtitles
       class Clean
         attr_reader :content

data/lib/appydave/tools/{subtitle_manager → subtitle_processor}/join.rb

@@ -2,7 +2,7 @@
 
 module Appydave
   module Tools
-    module SubtitleMaster
+    module SubtitleProcessor
       # Join multiple SRT files into one
       # - Supports folder, wildcards, sorting via FileResolver
       class Join
@@ -265,7 +265,10 @@ module Appydave
           end
         end
 
-        def initialize(folder: './', files: '*.srt', sort: 'inferred', buffer: 100, output: 'merged.srt', log_level: :info)
+        # rubocop:disable Metrics/ParameterLists
+        def initialize(folder: './', files: '*.srt', sort: 'inferred', buffer: 100, output: 'merged.srt',
+                       log_level: :info)
+          # rubocop:enable Metrics/ParameterLists
           @folder = folder
           @files = files
           @sort = sort

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.15.0'
+    VERSION = '0.16.0'
   end
 end

data/lib/appydave/tools.rb

@@ -16,8 +16,6 @@ require 'googleauth'
 require 'googleauth/stores/file_token_store'
 require 'webrick'
 
-require 'pry'
-
 require 'appydave/tools/version'
 require 'appydave/tools/debuggable'
 require 'appydave/tools/types/indifferent_access_hash'
@@ -50,8 +48,8 @@ require 'appydave/tools/name_manager/project_name'
 
 require 'appydave/tools/prompt_tools/prompt_completion'
 
-require 'appydave/tools/subtitle_manager/clean'
-require 'appydave/tools/subtitle_manager/join'
+require 'appydave/tools/subtitle_processor/clean'
+require 'appydave/tools/subtitle_processor/join'
 
 require 'appydave/tools/youtube_automation/gpt_agent'
 

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appydave-tools",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "AppyDave YouTube Automation Tools",
   "scripts": {
     "release": "semantic-release"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appydave-tools
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - David Cruwys
@@ -150,7 +150,10 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: "    AppyDave YouTube Automation Tools\n"
+description: |2
+      AppyDave Tools is a consolidated productivity toolkit for YouTube content creation workflow.
+      Includes single-purpose utilities for AI context gathering, subtitle processing, YouTube management, and more.
+      All tools in one codebase for easier maintenance, each operates independently.
 email:
 - david@ideasmen.com.au
 executables:
@@ -187,10 +190,27 @@ files:
 - bin/setup
 - bin/subtitle_manager-old.rb
 - bin/subtitle_manager.rb
+- bin/subtitle_processor.rb
 - bin/youtube_automation.rb
 - bin/youtube_manager.rb
+- docs/archive/codebase-audit-2025-01.md
+- docs/archive/documentation-framework-proposal.md
+- docs/archive/purpose-and-philosophy.md
+- docs/archive/test-coverage-quick-wins.md
+- docs/archive/tool-discovery.md
+- docs/archive/tool-documentation-analysis.md
 - docs/dam/overview.md
-- docs/usage/gpt-context.md
+- docs/tools/bank-reconciliation.md
+- docs/tools/cli-actions.md
+- docs/tools/configuration.md
+- docs/tools/gpt-context.md
+- docs/tools/index.md
+- docs/tools/move-images.md
+- docs/tools/name-manager.md
+- docs/tools/prompt-tools.md
+- docs/tools/subtitle-processor.md
+- docs/tools/youtube-automation.md
+- docs/tools/youtube-manager.md
 - exe/ad_config
 - exe/gpt_context
 - exe/prompt_tools
@@ -224,11 +244,11 @@ files:
 - lib/appydave/tools/name_manager/project_name.rb
 - lib/appydave/tools/prompt_tools/_doc.md
 - lib/appydave/tools/prompt_tools/prompt_completion.rb
-- lib/appydave/tools/subtitle_manager/_doc-clean.md
-- lib/appydave/tools/subtitle_manager/_doc-join.md
-- lib/appydave/tools/subtitle_manager/_doc-todo.md
-- lib/appydave/tools/subtitle_manager/clean.rb
-- lib/appydave/tools/subtitle_manager/join.rb
+- lib/appydave/tools/subtitle_processor/_doc-clean.md
+- lib/appydave/tools/subtitle_processor/_doc-join.md
+- lib/appydave/tools/subtitle_processor/_doc-todo.md
+- lib/appydave/tools/subtitle_processor/clean.rb
+- lib/appydave/tools/subtitle_processor/join.rb
 - lib/appydave/tools/types/array_type.rb
 - lib/appydave/tools/types/base_model.rb
 - lib/appydave/tools/types/hash_type.rb
@@ -245,9 +265,6 @@ files:
 - lib/appydave/tools/youtube_manager/reports/video_details_report.rb
 - lib/appydave/tools/youtube_manager/update_video.rb
 - lib/appydave/tools/youtube_manager/youtube_base.rb
-- lib/mj-paste-test/main.rb
-- lib/mj-paste-test/prompts.txt
-- lib/mj-paste-test/readme-leonardo.md
 - package.json
 - sig/appydave/tools.rbs
 homepage: http://appydave.com/gems/appydave-tools
@@ -276,5 +293,5 @@ requirements: []
 rubygems_version: 3.4.20
 signing_key:
 specification_version: 4
-summary: AppyDave YouTube Automation Tools
+summary: AppyDave productivity toolkit - CLI utilities for YouTube workflow automation
 test_files: []

data/lib/mj-paste-test/main.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-require 'io/console'
-
-# input_prompts_filename = 'prompts.txt'
-input_prompts_filename = '/Users/davidcruwys/dev/ai-prompts/midjourney/documentation/clean-prompts/input.txt'
-output_prompts_filename = '/Users/davidcruwys/dev/ai-prompts/midjourney/documentation/clean-prompts/processed.txt'
-
-count = 1
-
-File.readlines(input_prompts_filename).each do |line|
-  raw_prompt = line.strip
-
-  prompt = "/imagine prompt: #{raw_prompt}"
-
-  display_prompt = "#{count} :: #{prompt}"
-  puts display_prompt
-
-  IO.popen('pbcopy', 'w') { |f| f << prompt }
-  File.open(output_prompts_filename, 'a') { |f| f.puts raw_prompt }
-
-  count += 1
-
-  lines = File.readlines(input_prompts_filename)
-  lines.delete_at(0)
-  File.write(input_prompts_filename, lines.join)
-
-  if (count % 8).zero?
-    puts 'Press any key to continue...'
-    $stdin.getch
-    puts "\n"
-  else
-    sleep(5)
-  end
-end

data/lib/mj-paste-test/prompts.txt

@@ -1,18 +0,0 @@
-3D, software and app IT business, illustration, iphone, tablet, computer, graphs, datas, light green, white, grey --v 4
-Small and cute urban laboratory, 3d blender render, soft smooth lighting, rain background,100mm lens, 4k UHD, isometric, tilt – shift --v 5
-Small and cute urban laboratory, 3d blender render, soft smooth lighting, rain background,100mm lens, 4k UHD, isometric, tilt – shift --v 4
-clean gradient knolling 3D illustration design for professional saas software office automation, colored gradient blue white green and warm sunshine accents and neutral colors, with abstract lines, behance, dribbble --v 4
-ultra realistic tetris pattern , 5-Dimensional, Nonagon, Star Prism, Polygon, Happy Accidents, Refreshing, Strong, Binary, Hexadecimal, ray tracing, global illumination, octane render,metallic, shiny --v 4
-Tilt shift, depth of field, low poly, starry night, solid simple mobile game asset, diorama, tilt shift,depth of field, cute isometric clear view of cute [Marina Bay Sands], fairytale, orientalism, soft pastel colors, starry mystical night – time, volumetric lighting, dramatic lighting, vibrant colors,triadic color harmony, stars and moon on dark background, motes, dustlights, air particles,stardusts, vibrant vivid sharp clear, made with blender 3D, in the style of artstation and behance --v 5
-sustainability and blockchain theme, no text, showing crypto icons, information flow, mixing 3D and vector styles, images only,  --v 4
-cryptocurrency data charts, white background, white, concept art. 3d rendering illustration. vivid colors, depth of field, dramatic lighting, sharp focus, epic composition, 8k, UHD, natural light, photo realistic, maximum texture, HDR, FStop 1.8, High octane render, Unreal engine 5, photoshoot, DSLR, cinematic lighting, highly detailed, ray tracing, Cinematic, Photoshoot, Dramatic, DSLR, Ultra-Wide Angle, 32k, Ultra-HD, Super-Resolution, Bokeh blue soft light background, Backlight, AMOLED, Cinematic Lighting, Volumetric Lighting --v 4
-pixel cubes vector svg, brain as brain cloud with colorful flashes social impact and with a total white background photo in Kodak Color 400, professional photography, insta style, photographic style, Unreal Engine, Cinematic, Color Grading, Editorial Photography, Photography, Photoshoot, White Balance, background white, 32k --v 5
-finance charts, white background, white, concept art. 3d rendering illustration. vivid colors, depth of field, dramatic lighting, sharp focus, epic composition, 8k, UHD, natural light, photo realistic, maximum texture, HDR, FStop 1.8, High octane render, Unreal engine 5, photoshoot, DSLR, cinematic lighting, highly detailed, ray tracing, Cinematic, Photoshoot, Dramatic, DSLR, Ultra-Wide Angle, 32k, Ultra-HD, Super-Resolution, Bokeh blue soft light background, Backlight, AMOLED, Cinematic Lighting, Volumetric Lighting --v 4
-facebook cover, marketing charts, only charts displayed on various screens of Apple devices, laptop, mobile, 4k --v 4
-cup of coffee over a table, table with charts, volumetric ligh --v 4
-color cube wide gamut pantone all colors color space --v 5
-block network graph universe parallel connections 3D --v 5
-Tilt-shift futuristic city, night, skylines, ciberpunk by Felipe Pantone --v 4
-make a pop art deco epic city, tilt shift, with trees and topiary, a river running through the city, Cinematography, ultra detailed, 8k, photorealistic,hd, octane render, digitally rendered, award-winning photograph, timeless beauty, cinematic lighting, sophisticated color palette, cinematic focus, symmetrical balance, glowing, octane render, trending on artstation, 3d rendered, 3d --v 4
-3D isometric drawing, Asian restaurant, cyberpunk --v 4
-architect paper plan, on a desk, realistic picture, modern, design, 8k, --v 4