{"id":13616528,"url":"https://github.com/Comcast/caption-inspector","last_synced_at":"2025-04-14T00:32:32.799Z","repository":{"id":41325434,"uuid":"193114676","full_name":"Comcast/caption-inspector","owner":"Comcast","description":"Caption Inspector is a reference decoder for Closed Captions (CEA-608 and CEA-708).","archived":false,"fork":false,"pushed_at":"2024-07-09T17:23:37.000Z","size":19481,"stargazers_count":69,"open_issues_count":17,"forks_count":11,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-08-02T20:48:17.153Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://comcast.github.io/caption-inspector/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Comcast.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-21T14:46:40.000Z","updated_at":"2024-07-23T02:22:36.000Z","dependencies_parsed_at":"2023-01-22T10:30:51.966Z","dependency_job_id":null,"html_url":"https://github.com/Comcast/caption-inspector","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Comcast%2Fcaption-inspector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Comcast%2Fcaption-inspector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Comcast%2Fcaption-inspector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Comcast%2Fcaption-inspector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Comcast","download_url":"https://codeload.github.com/Comcast/caption-inspector/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223612183,"owners_count":17173590,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2024-08-01T20:01:29.810Z","updated_at":"2024-11-08T00:32:12.545Z","avatar_url":"https://github.com/Comcast.png","language":"C","funding_links":[],"categories":["HarmonyOS","C","Media Tools"],"sub_categories":["Windows Manager","Subtitle \u0026 Caption Tools"],"readme":"[![Build Status](https://travis-ci.com/Comcast/caption-inspector.svg?branch=master)](https://travis-ci.com/Comcast/caption-inspector)\n\nCaption Inspector\n=================\n\nThe Caption Inspector project builds a C library, C executable, and Docker image that can be used to extract and decode\nClosed-Captions from various Video or Caption File Formats. Caption Inspector Supports CEA-608 and CEA-708 in MPEG-2 and\nMPEG-4 (.mpg, .ts, and .mp4 containers), MCC (MacCaption Closed Captions), and SCC (Scenarist Closed Captions) files.\n\n![Overview](./docs/html/assets/content-images/Overview.png)\n\nCaption Inspector has a plugin pipeline architecture that can be configured in various ways and allows the user to add\nnew plugins to perform various transformations. Currently, the following are the main use cases that the Caption\nInspector Software covers:\n* Pulling Captions from a Video Asset and writing them to an MCC Caption File, a [CEA-608 Decode File](./docs/decoded608.md),\na [CEA-708 Decode File](./docs/decoded708.md), and a [Closed Caption Descriptor Decode File](./docs/decodeCCD.md).\n* Decoding a MCC Caption file and writing the decoded captions into  a [CEA-608 Decode File](./docs/decoded608.md),\na [CEA-708 Decode File](./docs/decoded708.md), and a [Closed Caption Descriptor Decode File](./docs/decodeCCD.md).\n* Decoding a SCC Caption file and writing the decoded captions into a MCC Caption File, a [CEA-608 Decode File](./docs/decoded608.md),\nand a [Closed Caption Descriptor Decode File](./docs/decodeCCD.md).\n\nBuilding and Running the Caption Inspector Executable Locally\n-------------------------------------------------------------\n\nCaption Inspector requires FFMPEG to be installed on your machine. Please download the appropriate\nversion of FFMPEG from [here](https://ffmpeg.org/download.html) and install it in your machine.\nCaption Inspector is known to run with FFMPEG Version 4.0.2.\n\nTo install FFMPEG Version 4.0.2, follow the below list (for Mac), using the Dockerfile as a reference:\n```\nbrew install nasm\nbrew install yasm\ncurl -s http://ffmpeg.org/releases/ffmpeg-4.0.2.tar.gz | tar zxvf - -C . \ncd ffmpeg-4.0.2/\n./configure  --enable-version3 --enable-hardcoded-tables --enable-shared --enable-static --enable-small --enable-libass --enable-postproc --enable-avresample --enable-libfreetype --disable-lzma --enable-opencl --enable-pthreads\nmake\nmake install\nmake distclean\n```\n\nWhile not required, Caption Inspector leverages a tool called MediaInfo to determine whether or not\nan asset is, or is not, Drop Frame. You can download the command line version of MediaInfo\n[here](https://mediaarea.net/en/MediaInfo/Download). Caption Inspector is known to run with\nMediaInfo Version 18.12 (found [here](https://mediaarea.net/download/binary/mediainfo/18.08/MediaInfo_CLI_18.08_Mac.dmg)).\n\n```\nmake caption-inspector\n./caption-inspector -h\n./caption-inspector -o . test/media/BigBuckBunny_256x144-24fps.ts\n./caption-inspector -o . test/media/Plan9fromOuterSpace.scc -f 2400\n./caption-inspector -o . test/media/NightOfTheLivingDead.mcc\n```\n\nRunning with the `-h` option will simply print out the help text. \n\nRunning against the video file `BigBuckBunny_256x144-24fps.ts` demonstrates decoding closed captions from a video file.\n\nRunning against the caption file `Plan9fromOuterSpace.scc` demonstrates decoding an SCC file and CEA-608 Captions, as well as\nconverting the contents of the SCC file into an MCC file.\n\nRunning against the caption file `NightOfTheLivingDead.mcc` demonstrates decoding an MCC file, CEA-608 Captions, and CEA-708 Captions.\n\nBuilding the Caption Inspector Executable Locally with MOV Support\n------------------------------------------------------------------\n\nCaption Inspector requires the inclusion of the [GPAC][https://gpac.wp.imt.fr/] Library. Specifically a modified library of GPAC which\ngets linked as a shared object is required. This library is located [here][https://github.com/Comcast/gpac-caption-extractor] and must be pulled and built.\nOnce the GPAC library has been built the same instructions are used as above.\n\n```\ngit clone https://github.com/Comcast/gpac-caption-extractor.git\ncd gpac-caption-extractor\nmake install\ncd ../caption-inspector\nmake ci_with_gpac\n```\n\nBuilding and Running Caption Inspector in a Docker Container\n------------------------------------------------------------\nObviously you need docker running on your local machine to build. Building inside of a docker image will remove the need\nto install any dependencies, but comes at the expense of a slightly more complicated command line execution. Another advantage\nof building Caption Inspector inside of the Docker Container is that it seamlessly integrates MOV support. All of the steps above\nto pull the GPAC library, build it, and then link it to Caption Inspector are done automagically in the Docker File.\n\n```\nmake docker\ndocker run -t caption-inspector -h\ndocker run -tv $(pwd):/files caption-inspector -o /files /files/test/media/BigBuckBunny_256x144-24fps.ts\ndocker run -tv $(pwd):/files caption-inspector -o /files /files/test/media/Plan9fromOuterSpace.scc -f 2400\ndocker run -tv $(pwd):/files caption-inspector -o /files /files/test/media/NightOfTheLivingDead.mcc\n```\n\nIn the `docker run` command, your current working directory will be remapped to `/files` inside of the container, so\nyou will need to prefix your input and output paths to that so that it can place the files in the correct spot. For\nthis example, the output file is located in the current directory `./` and the input file is located in a directory\nunderneath the current directory, specifically `./test/media/*`.\n\nRegression Testing the Caption Inspector Executable\n---------------------------------------------------\n\nWhile the testing is not complete yet, there are several Unit Tests, Integration Tests, and System Tests that run\non the Caption Inspector Codebase. These are intended to be run as integration tests and verify that nothing has\nbroken as a result of a change. They are run as part of a pull request, but for debugging purposes they can also\nbe run locally (even in an IDE) before a pull request is issued. The easiest way to run these is inside of docker,\nas the dependencies are handled for you. But if you need to run them with an IDE/debugger, they can also be run\nfrom the command line. To run the regression tests from inside of docker, you can build the docker image and run\nthe tests from the root directory.\n\n```\nmake docker-test\n```\n\nThe output generated by this activity can give information about any test case that does not pass, but even more useful\nis an HTML file that is the output of the test. It contains all of the tests, and their statuses. It is in the root\ndirectory and takes the form `\u003cdate\u003e__\u003ctime\u003e_test_output.html`. To view the results you can open the file inside of\na browser.\n\nTo run the regression tests from the command line, you need to install Xunit Viewer, which can be found [here](https://github.com/lukejpreston/xunit-viewer).\nXunit Viewer is the application that takes the Xunit XML and converts it into a beautified HTML format. Once you have\nXunit Viewer installed, or if you ignore it, you just need to build and run the regression tests from the test directory.\n\n```\ncd test\nmake test\n```\n\nThe tests are a mix of C and Python, depending on which made more sense for the specific test. The build system will\naggregate all of the results from the tests in both languages.\n\nLeveraging the Caption Inspector Functionality from Python\n----------------------------------------------------------\nC was chosen as the language for Caption Inspector because of interoperability with FFMPEG and ease of implementation of\nthe specifications. While that choice made sense, there are lots of reasons to want to access this functionality as a\nlibrary from a higher level language than C. To that end Python bindings, using CTypes, were added to the C functionality\nwhich can be compiled into a shared library and referenced from Python code. To use this functionality you just need\nto build the shared library using the command `make sharedlib`. Then leverage the file `python/cshim.py` inside of your\nPython code, making sure that it knows where to find the shared library with the Caption Inspector Code.\n\nThe Caption Inspector code that makes this possible, and the library it generates, can likely be reused for other high\nlevel languages such as Java/JNI, Golang/Cgo, etc. No work has been done in those languages, but if you do end up using\nit in a new language, please consider submitting the results back to the repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FComcast%2Fcaption-inspector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FComcast%2Fcaption-inspector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FComcast%2Fcaption-inspector/lists"}