gob2json

Video Silence and Static Interval Detection and Merging Tool

A Go tool that detects intervals in videos where both "silence" and "static frame" conditions are met, and generates timeline files for use with auto-editor.

🎯 Core Features

Performs intersection operations on two independent analysis results:

1. auto-editor silence segments (autoeditor.json) - Contains audio silence intervals
2. vcmp static frame segments (.pb.zst file) - Contains video static frame intervals (Protocol Buffers + Zstandard compression)

Output: Intervals that are both silent AND static, formatted as auto-editor v1 timeline JSON, ready for video editing.

📋 Use Cases

• Automatically remove "frozen" segments from videos (static frame + no sound)
• Batch process invalid segments in video tutorials, screen recordings, and stream replays
• Precisely locate problem areas requiring manual editing

🚀 Quick Start

Installation

# Clone repository
git clone <repository-url>
cd gob2json

# Build and install to system path
make install

Usage Steps

1. Prepare Input Files

   Place two files in your working directory:

   • autoeditor.json - Timeline file generated by auto-editor
   • *.pb.zst - Video analysis result file generated by vcmp (Protocol Buffers + Zstandard compressed format, must contain suggested threshold data)

2. Run Program

   gob2json [threshold] [minDuration] [output_base]

   Parameter Description:

   • threshold (optional): Difference threshold (integer).
     • If omitted: Program automatically uses SuggestedThreshold from .pb.zst file
     • If provided: Overrides auto-suggested value and uses specified threshold
   • minDuration (optional): Minimum exclusion duration in seconds, must be positive, defaults to 20.0 seconds
     • Note: To specify minDuration, you must explicitly provide the threshold parameter
   • output_base (optional): Output file base name, defaults to input JSON filename

3. Use Output File

   The program generates a timestamped JSON file, such as autoeditor_20231215_143022.json, which can be used directly with auto-editor:

   auto-editor input.mp4 --edit timeline:autoeditor_20231215_143022.json

Examples

# Mode 1: Fully automatic
# Use suggested threshold from pb.zst file, default minimum exclusion duration 20 seconds
gob2json

# Mode 2: Manually specify threshold
# Force use threshold 30, default minimum exclusion duration 20 seconds
gob2json 30

# Mode 3: Specify threshold and duration
# Force use threshold 30, set minimum exclusion duration to 2.5 seconds
gob2json 30 2.5

# Mode 4: Specify output filename
gob2json 30 2.5 cleaned_output

🔧 How It Works

┌─────────────────┐     ┌─────────────────┐
│  autoeditor.json│     │  analysis.pb.zst│
│   (静音区间)    │     │  (静止画面区间) │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     ↓
            ┌─────────────────┐
            │   交集运算      │
            │ (重叠区间检测)  │
            └────────┬────────┘
                     ↓
         ┌───────────────────────┐
         │  output_timestamp.json │
         │  (静音+静止的区间)     │
         │   速度标记为 0.0       │
         └───────────────────────┘

Key Logic

1. Parse Input Files

   • Read frame difference data (DiffCounts) and suggested threshold (SuggestedThreshold) from .pb.zst file
   • Read timeline segments (Chunks) from autoeditor.json

2. Interval Detection

   • Static frame intervals: Consecutive frames where difference value exceeds threshold (≥ minimum duration)
   • Silence intervals: Segments in timeline with speed 0.0 or 9999.0

3. Intersection Calculation

   • Find overlapping parts of two interval sets
   • Merge adjacent or overlapping intervals

4. Generate Output

   • Set playback speed of intersection intervals to 0.0 (exclusion marker)
   • Maintain original speed for other intervals
   • Output JSON conforming to auto-editor v1 specification

📁 Project Structure

gob2json/
├── main.go          # Entry function, argument parsing and auto-threshold logic
├── vcmp.go          # .pb.zst file I/O, AnalysisResult data structure definition
├── autoeditor.go    # auto-editor JSON format parsing and generation
├── merge.go         # Core algorithms: interval detection, intersection calculation, merge export
├── proto/           # Protocol Buffers definitions
│   └── analysis.proto
├── go.mod           # Go module definition
├── Makefile         # Build scripts
└── README.md        # This document

🛠️ Development Commands

# Build binary
make build

# Install to system path (requires sudo)
make install

# Uninstall
make uninstall

# Clean build files
make clean

# Display help information
make help

📊 Data Format

Input Format

auto-editor JSON (v1):

{
  "version": "1",
  "source": "video.mp4",
  "chunks": [
    [0.0, 10.5, 1.0],     // [start, end, speed]
    [10.5, 15.0, 0.0],    // speed 0.0 = silence segment
    [15.0, 30.0, 1.0]
  ]
}

vcmp .pb.zst file structure (Protocol Buffers):

syntax = "proto3";
package analysis;

message AnalysisResult {
  string video_file = 1;           // 被分析的视频文件路径
  double fps = 2;                  // 视频帧率
  int32 width = 3;                 // 视频宽度（像素）
  int32 height = 4;                // 视频高度（像素）
  int32 total_frames = 5;          // 视频总帧数
  double suggested_threshold = 6;  // 自动计算的建议阈值
  repeated uint32 diff_counts = 7; // 每一帧的差异像素数量
}

Files use Zstandard (zstd) compression to reduce storage space.

Output Format

Same format as input auto-editor JSON, but intersection intervals have speed set to 0.0.

⚙️ Configuration

Constants (can be modified in merge.go)

const (
    MinExclusionDurationSeconds = 20.0   // Default minimum exclusion duration
    ExcludedSpeedMarker = 0.0           // Exclusion region speed marker
    SkipSpeedHigh = 9999.0              // High speed marker
    SkipSpeedZero = 0.0                 // Zero speed marker
)

Threshold Mechanism

Program prioritizes command line arguments. If no command line arguments provided, attempts to use SuggestedThreshold stored in .pb.zst file. If both unavailable, program exits with error.

• Low threshold: More strict, may treat minor movements (like mouse jitter) as non-static
• High threshold: More lenient, tolerates certain frame changes

🔍 Troubleshooting

Common Issues

1. Input files not found

   ✗ 未找到 .pb.zst 文件
   

   → Ensure .pb.zst and .json files exist in working directory

2. Missing threshold

   ✗ 缺少 threshold 参数，且分析结果中未包含有效建议阈值
   

   → The .pb.zst file does not contain suggested threshold. Must manually specify an integer threshold in command line (e.g., gob2json 30)

3. Multiple JSON files found

   ⚠ 发现多个 .json 文件，使用: autoeditor.json
   

   → Program prioritizes file named autoeditor.json

4. Version error

   ✗ 版本号无效: 期望 "1"，得到 "3"
   

   → Currently only supports auto-editor v1 format timeline

🤝 Contributing

Issues and Pull Requests are welcome!

Development Environment Requirements

• Go 1.21 or higher
• Protocol Buffers compiler (protoc)
• Familiarity with auto-editor and vcmp tools

📄 License

This project is open sourced under GPL-3.0 License.

🔗 Related Projects

• auto-editor - Automatic video editing tool
• vcmp - Video frame comparison tool