Rendering markdown & diagrams...
1 # AIR FORCE DOCTRINE NOTE (AFDN) 25-1
2 ## DIRECTIVE 04: AUTONOMOUS RESEARCH INFOGRAPHIC VIDEO SYNTHESIS & FLEET AUDIT
3 **CLASSIFICATION:** UNCLASSIFIED // NON-COMPARTMENTED // OPERATIONAL DIRECTIVE
4 **COMMAND AUTHORITY:** CHIEF ARCHITECT (SHUBHAM)
5 **DISTRIBUTION:** NEURALOS COMMAND FLEET (MAC MASTER // DELL TACTICAL BODY)
6 **EFFECTIVE DATE:** 2026-11-09
7 **SUPERSEDES:** PREVIOUS DRAFTS & AD-HOC VIDEO NOTES
8
9 ---
10
11 ```
12 ========================================================================================
13 AIR FORCE DOCTRINE NOTE (AFDN) 25-1 // OPERATIONAL DIRECTIVE 04
14 SUBJECT: RESEARCH EXPLORATION & AUTOMATED INFOGRAPHIC VIDEO SYNTHESIS SYSTEM
15 NODES ENGAGED:
16 • MASTER BRAIN: Apple Silicon Mac (16GB Unified RAM, Metal GPU)
17 • TACTICAL BODY: Dell Inspiron 3521 (dell-ss @ 192.168.31.65 / 100.93.213.110)
18 • STORAGE ANCHORS: /dev/sda3 (L1 SSD), /dev/sda5 (L2 Drive D - RO), /dev/sdb1 (1TB HDD)
19 ========================================================================================
20 ```
21
22 ---
23
24 ## SECTION I: COMPREHENSIVE CLUSTER AUDIT & DOCTRINE ALIGNMENT
25
26 An exhaustive audit of all active hardware, memory subsystems, network topologies, and specification documents was conducted under AFDN 25-1 standards on 2026-11-09:
27
28 ### 1.1 Hardware & Subsystem Status Matrix
29
30 | Subsystem | Node / Device | Operational State | Doctrine Assessment |
31 | :--- | :--- | :--- | :--- |
32 | **Cognitive Brain** | Mac (16 GB Unified) | **ONLINE** | Metal GPU acceleration active for 7B 4-bit abliterated model; memory pressure **GREEN** (7.7 GB available headroom). |
33 | **Tactical Body** | Dell Node-01 (`dell-ss`) | **ONLINE** | 24/7 headless, lid closed, sleep masked (`/dev/null`), Wi-Fi powersave disabled (Permanent Caffeinate Policy verified). |
34 | **AI Background Agent** | `picoclaw` (v0.3.1) | **ONLINE** | Running via systemd (`picoclaw.service`) on `:18790` with 6.6 MB RAM footprint; hourly health cron active. |
35 | **Non-Volatile Memory** | SQLite WAL Engine | **ONLINE** | 16 nodes and directed weighted edges in `/var/neural_memory/data/graph_memory.db`; <2ms query latency. |
36 | **Protected Storage** | `/dev/sda5` (`/mnt/drive_d`) | **SECURED (RO)** | Mounted read-only via `/etc/fstab` (`UUID=64306B35306B0CFC`); **ROE-01 strictly enforced**. |
37 | **Mass Storage** | `/dev/sdb1` (`/mnt/hdd1`) | **OPERATIONAL (RW)** | 1TB external drive mounted at `/mnt/hdd1/`; dedicated target for downloads, render outputs, and videos. |
38 | **Media Vault & C2 UI** | `web_status.py` (:8080) | **ONLINE** | HTTP 206 Byte-Range streaming active; instant folder search and media viewing verified over LAN & Tailscale. |
39 | **Encrypted Mesh** | Tailscale v1.104.5 | **CONNECTED** | Dell IP `100.93.213.110` authenticated to `ssharma38w@` tailnet. |
40 | **Tor Anonymity Layer** | Tor SOCKS5 Daemon | **READY FOR ACTIVATION** | APT packages staged; configuration planned for `127.0.0.1:9050` SOCKS5h remote DNS. |
41
42 ### 1.2 Documentation Audit
43
44 - [`HLD.md`](file:///Users/shubhamsharma/project/HLD.md) & [`LLD.md`](file:///Users/shubhamsharma/project/LLD.md): High-Level and Low-Level architecture conform to multi-node design; requires formal integration of the Video Synthesis Pipeline.
45 - [`backlog.md`](file:///Users/shubhamsharma/project/backlog.md): BL-001 (Tailscale), BL-002 (Memory Sync), BL-004 (Model Compilation), and BL-008–BL-010 marked **COMPLETED**.
46 - [`SYSTEM_SPEC.md`](file:///Users/shubhamsharma/project/SYSTEM_SPEC.md) & [`dell-ss_spec.md`](file:///Users/shubhamsharma/project/dell-ss_spec.md): Specs accurately reflect port 8080 telemetry, ROE-01 constraints, and persistent caffeinate policy.
47
48 ---
49
50 ## SECTION II: MISSION & PRODUCT SPECIFICATION
51
52 ### 2.1 The Strategic Vision
53 The Chief Architect requires an automated, production-grade **Research Paper Explainer & Infographic Video Synthesis Subsystem**.
54
55 The pipeline ingests complex scientific publications (e.g. arXiv PDFs, technical whitepapers), extracts key insights, generates an engaging pedagogical script, clones Shubham’s authentic natural voice, renders mathematical animations and motion graphics, and compiles polished 1080p/4K explainer videos for distribution.
56
57 ### 2.2 Product Definition & Key Features
58 * **Output Format**: 1080p 60fps (16:9 for YouTube/Desktop and 9:16 vertical for Shorts/Reels).
59 * **Voice Track**: Highly natural, conversational, clone of Shubham's voice with authentic cadence, pauses, and zero robotic monotone.
60 * **Visual Style**: High-clarity **3Blue1Brown-style mathematical animations**, structural architecture diagrams, code callouts, highlighted paper excerpts, and kinetic typography.
61 * **Automation Degree**: End-to-end automated generation from a single paper identifier (arXiv ID, DOI, or local PDF), with optional human-in-the-loop storyboard review.
62
63 ---
64
65 ## SECTION III: SUBSYSTEM REQUIREMENTS & TECHNICAL ARCHITECTURE
66
67 ```mermaid
68 flowchart TD
69 subgraph Intake["Subsystem A: Paper Intake & Decomposition"]
70 PDF["Scientific Paper (PDF / arXiv)"]
71 Parser["PyMuPDF / Nougat OCR / Markdown Extractor"]
72 Structure["Structured Paper Data:\n• Core Thesis & Novelty\n• Equations & Architecture\n• Key Figures & Benchmarks"]
73 PDF --> Parser --> Structure
74 end
75
76 subgraph Scripting["Subsystem B: Cognitive Storyboarding"]
77 LLM["DeepSeek-R1 Reasoning Engine\n(Master Mac Metal GPU)"]
78 Storyboard["5-Stage Pedagogical Storyboard:\n1. Hook & The Core Dilemma\n2. The Intuitive Metaphor\n3. Mathematical / Architectural Deep-Dive\n4. Experimental Verification & Benchmarks\n5. Strategic Impact & Takeaways"]
79 Structure --> LLM --> Storyboard
80 end
81
82 subgraph VoiceEngine["Subsystem C: Acoustic Cloning & TTS"]
83 VoiceSample["Shubham Voice Profile\n(15-30s clean WAV enrollment)"]
84 F5TTS["F5-TTS Flow-Matching DiT\n(Mac Metal / Cloud Fallback)"]
85 AudioTrack["Natural Narration Audio\n(48kHz WAV + Timestamp Timings)"]
86 Storyboard --> F5TTS
87 VoiceSample --> F5TTS --> AudioTrack
88 end
89
90 subgraph MotionGraphics["Subsystem D: Infographic Animation Engine"]
91 ManimEngine["Manim Community Engine\n• Vector Math & Graph Morphing\n• Neural Net Layer Animations\n• Architecture Flowcharts"]
92 SlideEngine["Marp / Reveal.js Headless Renderer\n• Code snippets & Paper highlights"]
93 VisualAssets["Visual Video Chunks (1080p60 MP4)"]
94 Storyboard --> ManimEngine --> VisualAssets
95 Storyboard --> SlideEngine --> VisualAssets
96 end
97
98 subgraph Assembly["Subsystem E: Audio-Visual Assembly & Final Render"]
99 FFmpegEngine["FFmpeg Assembly Pipeline (Dell / Mac)\n• Precision Audio-Video Sync\n• Dynamic Ambient Audio Ducking\n• Styled Subtitle Burning (.ass / .vtt)"]
100 FinalVideo["Final Master Video (.mp4)\nPublished to /mnt/hdd1/MOvies/Research/"]
101 AudioTrack --> FFmpegEngine
102 VisualAssets --> FFmpegEngine --> FinalVideo
103 end
104
105 subgraph Distribution["Subsystem F: Vault Delivery & Stremio Stream"]
106 VaultUI["Media Vault UI (:8080)"]
107 Stremio["Stremio Private Addon (:7000)"]
108 FinalVideo --> VaultUI
109 FinalVideo --> Stremio
110 end
111 ```
112
113 ---
114
115 ## SECTION IV: DETAILED SUBSYSTEM SPECIFICATIONS
116
117 ### 4.1 Subsystem A: Research Ingestion & Decomposition Engine
118 * **Intake Formats**: arXiv URL, Semantic Scholar DOI, or raw PDF in `/mnt/hdd1/research_papers/`.
119 * **Extraction Stack**:
120 - `pymupdf` (fitz): Ultra-fast text, figure, and table coordinate extraction.
121 - Paper section segmentation: Abstract, Introduction, Method, Architecture, Mathematical Formulations, Experimental Results.
122 - Figure extraction: Isolates high-resolution raster and vector diagrams directly from PDF streams.
123
124 ### 4.2 Subsystem B: Cognitive Storyboarding & Scriptwriting
125 * **Cognitive Engine**: Local `DeepSeek-R1-Distill-Qwen-7B-abliterated` on Master Mac (with Gemini API fallback for large 100k context windows).
126 * **Script Architecture (The 5-Act Technical Explainer Pattern)**:
127 1. **Act I (0:00–0:45) — The Failure Mode**: Why existing techniques fail; the exact problem the researchers set out to solve.
128 2. **Act II (0:45–1:45) — The Intuitive Breakthrough**: A physical or visual metaphor explaining the fundamental mechanism without jargon.
129 3. **Act III (1:45–3:30) — The Architecture & Math**: Equations rendered step-by-step with Manim animations; transformer attention maps; tensor flows.
130 4. **Act IV (3:30–4:30) — Benchmark Breakdown**: Empirical performance against baselines (bar charts, Pareto frontiers, latency tradeoffs).
131 5. **Act V (4:30–5:00) — Tactical Takeaway**: How engineers can apply this technique today; links to GitHub implementations.
132 * **Output Artifact**: Machine-readable JSON containing `scene_id`, `spoken_narration`, `visual_type` (`manim`, `diagram`, `slide`), `animation_spec`, and `duration_estimate`.
133
134 ### 4.3 Subsystem C: Shubham Voice Cloning & Acoustic Synthesis
135 * **Acoustic Fidelity Requirement**: Indistinguishable from the Chief Architect's authentic voice; includes natural micro-pauses, technical inflection, and vocal warmth.
136 * **Primary Engine — F5-TTS (Flow-Matching Non-Autoregressive Diffusion)**:
137 - **Why F5-TTS**: Zero-shot voice cloning utilizing a Diffusion Transformer (DiT). Requires only a single **15–30 second clean WAV audio sample** of Shubham's voice with an exact reference transcript.
138 - **Inference Hardware**: Runs directly on Mac Apple Silicon via PyTorch Metal (MPS) or via local Python environment.
139 - **Pacing & Alignment**: Generates word-level timestamps (`whisperX` or `ctc-forced-aligner`) to enable millisecond-accurate animation synchronization.
140 * **Secondary / Cloud Engine — ElevenLabs Professional Voice Clone (PVC)**:
141 - Fallback option for commercial broadcast quality with variable emotion/emphasis tags (`<break time="0.5s"/>`, emphasis, pacing).
142
143 ### 4.4 Subsystem D: Programmatic Infographic & Animation Engine
144 * **Primary Visual Renderer — Manim Community Edition (Python)**:
145 - Standardized mathematical and procedural animation library (developed by 3Blue1Brown).
146 - Used for:
147 - Dynamic geometric transformations and coordinate grids.
148 - Neural network graph visualizations (nodes, weighted activations, feed-forward pulses).
149 - Mathematical formula derivation using LaTeX typesetting.
150 * **Secondary Visual Renderer — Marp / Remotion**:
151 - Code syntax blocks with kinetic line highlighting.
152 - Clean card callouts and paper figure side-by-side comparisons.
153
154 ### 4.5 Subsystem E: Audio-Visual Assembly & FFmpeg Post-Production
155 * **Synchronization Protocol**:
156 - The duration of each animation scene dynamically adjusts to match the duration of the corresponding cloned voice narration.
157 * **Audio Engineering**:
158 - Voice normalization: EBU R128 loudness standard (-16 LUFS for YouTube/Web).
159 - Low-volume background ambient tech synth track with **automatic sidechain audio ducking** (-12dB duck during voice activity, smooth 300ms recovery).
160 * **Subtitle Engine**:
161 - Burned-in kinetic subtitles with word-by-word highlight (via `.ass` subtitle format generated automatically from Whisper timestamps).
162
163 ---
164
165 ## SECTION V: FLEET COMPUTE ALLOCATION & EXECUTION TOPOLOGY
166
167 To maximize efficiency and preserve hardware longevity, computational tasks are allocated strictly according to node strengths:
168
169 | Task / Workload | Assigned Node | Compute Engine | Justification |
170 | :--- | :--- | :--- | :--- |
171 | **PDF Ingestion & Storage** | **Dell Node-01** | Python / `/mnt/hdd1` | Mass storage volume holds raw papers and archives. |
172 | **Cognitive Scriptwriting** | **Master Mac** | DeepSeek-R1 / Metal | Requires fast 30+ tok/s reasoning throughput. |
173 | **Voice Cloning (F5-TTS)** | **Master Mac** | PyTorch MPS (Metal) | High memory bandwidth and unified RAM accelerate diffusion sampling. |
174 | **Manim Vector Rendering** | **Dell Node-01** | Python 3 / Cairo / FFmpeg | Headless 24/7 background rendering offloads Mac CPU. |
175 | **Final Assembly & Transcode** | **Dell Node-01** | `ffmpeg` (x264 / AAC) | Output lands directly on `/mnt/hdd1/MOvies/Research/`. |
176 | **Streaming & Distribution** | **Dell Node-01** | Web Vault (:8080) / Stremio | Immediate playback over LAN & Tailscale. |
177
178 ---
179
180 ## SECTION VI: STANDING RULES OF ENGAGEMENT (ROE-01 COMPLIANCE)
181
182 1. **ROE-01 ABSOLUTE MANDATE**: Under no circumstance shall any temporary render file, intermediate video frame, audio buffer, or script be written to partition `/dev/sda5` (`/mnt/drive_d`).
183 2. **Dedicated Target Folders**:
184 - Intermediate scratch files: `/mnt/hdd1/video_scratch/`
185 - Voice sample profiles: `/var/neural_memory/data/voice_profiles/`
186 - Completed video library: `/mnt/hdd1/MOvies/Research/`
187 3. **Bandwidth & Resource Throttling**:
188 - Manim background rendering on Dell is assigned `nice -n 10` to guarantee the Web Vault and PicoClaw agent remain 100% responsive.
189
190 ---
191
192 ## SECTION VII: EXECUTION PHASES & MILESTONES
193
194 - [ ] **Phase 1: Voice Profile Enrollment (Shubham Voice Profile)**:
195 - Record or select a 30-second clean audio sample (`shubham_reference.wav`) and transcribe it.
196 - Install and verify `F5-TTS` on Mac Apple Silicon.
197 - [ ] **Phase 2: Paper Ingestion & Decomposition Tool (`paper_to_script.py`)**:
198 - Build arXiv / PDF parser and prompt template for 5-act technical storyboards.
199 - [ ] **Phase 3: Manim Animation Template Library**:
200 - Create reusable animation modules for neural network layers, equations, and data charts.
201 - [ ] **Phase 4: Unified Compiler Pipeline (`synthesize_explainer.py`)**:
202 - Connect script → voice → animation → FFmpeg assembly → Web Vault.
203 - [ ] **Phase 5: PicoClaw Autonomous Skill (`create-paper-video`)**:
204 - Allow triggering the entire pipeline with a single command:
205 `picoclaw agent -m "Generate video for arXiv:2401.12345"`
206