{"id":37231530,"url":"https://github.com/debuggerx01/flutter_mcap_parser","last_synced_at":"2026-01-15T03:44:23.991Z","repository":{"id":331884986,"uuid":"1132183516","full_name":"debuggerx01/flutter_mcap_parser","owner":"debuggerx01","description":"一个高性能的 Flutter MCAP 文件解析库。底层基于 Rust 开发，通过 flutter_rust_bridge 连接，专为处理机器人日志数据（如 ROS 2 / Foxglove）设计。","archived":false,"fork":false,"pushed_at":"2026-01-11T13:55:46.000Z","size":304,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T17:29:20.329Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/debuggerx01.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-11T13:45:44.000Z","updated_at":"2026-01-11T13:55:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/debuggerx01/flutter_mcap_parser","commit_stats":null,"previous_names":["debuggerx01/flutter_mcap_parser"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/debuggerx01/flutter_mcap_parser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debuggerx01%2Fflutter_mcap_parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debuggerx01%2Fflutter_mcap_parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debuggerx01%2Fflutter_mcap_parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debuggerx01%2Fflutter_mcap_parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/debuggerx01","download_url":"https://codeload.github.com/debuggerx01/flutter_mcap_parser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debuggerx01%2Fflutter_mcap_parser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28413462,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-15T03:44:23.438Z","updated_at":"2026-01-15T03:44:23.983Z","avatar_url":"https://github.com/debuggerx01.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# flutter_mcap_parser\n\n一个高性能的 Flutter MCAP 文件解析库。底层基于 Rust 开发，通过 `flutter_rust_bridge` 连接，专为处理机器人日志数据（如 ROS 2 / Foxglove）设计。\n\n## ✨ 特性\n\n* **🚀 高性能**：核心解析逻辑由 Rust 编写，通过 FFI 调用，解析速度极快且内存安全。\n* **🛠️ 全面支持**：支持读取 Schema, Channel, Message, Metadata, Attachment 等所有 MCAP 核心记录。\n* **📂 多种输入源**：支持从 **文件路径**、**内存二进制 (Uint8List)** 或 **Flutter Assets** 读取。\n* **⚡️ 按需解析**：智能优化策略。只有当你传入了对应的回调函数时（例如 `onMessage`），底层才会去解析该类型的数据，最大化提升性能。\n* **🌊 流式处理**：基于 Dart Stream 和 Rust StreamSink，不会阻塞 UI 线程。\n\n## 📦 安装\n\n1. 在 `pubspec.yaml` 中添加依赖：\n\n```yaml\ndependencies:\n  flutter_mcap_parser: ^0.1.0 # 请替换为实际版本\n```\n\n2. 确保你的 Flutter 环境已经配置好 Rust 编译环境（如果你是从源码编译）。\n\n## 🚀 快速开始\n\n### 1. 初始化\n\n在使用任何解析功能之前，**必须**先调用初始化方法。通常建议在 `main()` 函数中完成。\n\n```dart\nvoid main() async {\n  WidgetsFlutterBinding.ensureInitialized();\n\n  // 初始化底层 Rust 库\n  await McapParser.init();\n\n  runApp(const MyApp());\n}\n```\n\n### 2. 读取本地文件\n\n这是最常用的方式，适用于处理存储设备上的大文件。\n\n```dart\nimport 'package:flutter_mcap_parser/flutter_mcap_parser.dart';\n\nvoid parseFile() {\n  McapParser.parseFromPath(\n    \"/sdcard/logs/robot_data.mcap\",\n    // 监听 Channel 信息\n    onChannel: (channel) {\n      print(\"发现话题: ${channel.topic} (SchemaID: ${channel.schemaId})\");\n    },\n    // 监听 Schema 定义\n    onSchema: (schema) {\n      print(\"发现数据定义: ${schema.name} (${schema.encoding})\");\n    },\n    // 监听具体消息\n    onMessage: (message) {\n      print(\"收到消息: 话题ID=${message.channelId}, 时间=${message.publishTime}\");\n      // message.data 是 Uint8List，需要根据 schema 解码\n    },\n    // 错误处理\n    onError: (err) =\u003e print(\"解析出错: $err\"),\n    // [必填] 解析结束回调\n    onEnd: () {\n      print(\"✅ 文件解析完成\");\n    },\n  );\n}\n```\n\n### 3. 读取 Flutter Assets\n\n适用于读取打包在 App 内的示例数据或配置文件。\n\n```dart\nvoid parseAsset() {\n  McapParser.parseFromAssets(\n    \"assets/sample.mcap\",\n    onMetadata: (meta) {\n      print(\"元数据: ${meta.metadata}\");\n    },\n    onEnd: () =\u003e print(\"Assets 解析结束\"),\n  );\n}\n```\n\n### 4. 读取内存数据 (Bytes)\n\n适用于网络下载或通过其他方式获取到的二进制流。\n\n```dart\nvoid parseBytes(Uint8List mcapData) {\n  McapParser.parseFromBytes(\n    mcapData,\n    onMessage: (msg) {\n      // 处理消息...\n    },\n    onEnd: () =\u003e print(\"内存数据解析结束\"),\n  );\n}\n```\n\n## 📖 API 参考\n\n### `McapParser`\n\n#### `static Future init()`\n\n初始化 FFI 绑定。必须在使用前调用一次。\n\n#### 解析方法\n\n所有解析方法都支持以下命名参数（回调函数）。**注意：只有传入了非空的回调，底层才会解析对应的数据类型。**\n\n| 参数名            | 类型                                  | 说明                      |\n|:---------------|:------------------------------------|:------------------------|\n| `onMessage`    | `void Function(McapMessage)`        | 每当读到一条消息记录时触发。          |\n| `onChannel`    | `void Function(McapChannelInfo)`    | 每当读到话题通道定义时触发。          |\n| `onSchema`     | `void Function(McapSchemaInfo)`     | 每当读到数据格式定义时触发。          |\n| `onMetadata`   | `void Function(McapMetadataInfo)`   | 每当读到用户元数据时触发。           |\n| `onAttachment` | `void Function(McapAttachmentInfo)` | 每当读到附件文件时触发。            |\n| `onError`      | `void Function(String)`             | 当底层发生错误（如文件损坏、解压失败）时触发。 |\n| `onEnd`        | `void Function()`                   | **(必填)** 当文件读取流正常结束时触发。 |\n\n#### 方法签名\n\n1. **`parseFromPath(String path, { ... })`**\n    * 直接在 Rust 层打开文件，性能最高，内存占用最低。推荐用于大文件。\n\n2. **`parseFromAssets(String assetsKey, { ... })`**\n    * 使用 `rootBundle` 加载 Asset 并转换为 Uint8List 传给底层。\n\n3. **`parseFromBytes(Uint8List bytes, { ... })`**\n    * 直接解析内存中的二进制数据。\n\n## ⚠️ 注意事项\n\n1. **性能优化提示**：如果你只关心话题列表（Channel），请不要传入 `onMessage` 回调。这样解析器会直接跳过所有消息数据块（Chunk），解析速度会提升 100 倍以上。\n2. **主线程阻塞**：虽然解析是在 Rust 线程池或异步流中进行的，但在回调极其频繁的情况下（如每秒 10 万条消息），Dart 端的 `onMessage` 执行可能会占用较多 UI\n   线程资源。建议在回调中进行轻量级处理。\n\n## 🤝 贡献\n\n欢迎提交 Issue 和 Pull Request！\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdebuggerx01%2Fflutter_mcap_parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdebuggerx01%2Fflutter_mcap_parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdebuggerx01%2Fflutter_mcap_parser/lists"}