Package: lachesis
lachesisautomates the segmentation of a transcript into closed
captionsVersion: 0.0.3Date: 2017-01-26Developed by:Alberto PettarinLicense: the GNU Affero General Public License Version 3 (AGPL v3)Contact:info@readbeyond.itDO NOT USE THIS PACKAGE IN PRODUCTION UNTIL IT REACHES v1.0.0 !!!Goallachesisautomates the segmentation of a transcript into closed
captions (CCs).The general idea is that writing a transcription (raw text) is easier
and faster than writing CCs, especially if you need to respect
constraints like a certain minimum/maximum number of characters per
line, a maximum number of lines per CC, etc.You can transcribe your video into raw text andlachesiswill take
on the job of segmenting the text into CCs for you. Once you have the
CCs, you can use aforced
alignerlikeaeneasto align them with
the audio of your video, obtaining a subtitle file (SRT, TTML, VTT,
etc.).Withlachesisand a forced aligner, the manual labor for producing
CCs for a video is reduced to a. transcribing the video in raw text
form, and b. checking the final CCs and audio alignment. Instead of
transcribing from scratch, you can even start by checking/editing a
rough transcription made by an automated speech recognition engine, like
the “automatic CCs” from YouTube, speeding the process up further.The “magic” behindlachesisconsists in combining machine learning
techniques likeconditional random
fields(CRF)
and classical NLP tools likePOS
taggingandsentence
segmentationto
split the text into CC lines. The machine learning models are learned
from existing, manually-edited, high-quality CCs, like those ofTED/TEDxtalks on YouTube. The NLP tools come from the well-established, free NLP
libraries for Python listed below.In summary,lachesiscontains the following major functions:download closed captions from YouTube;parse closed caption TTML files (downloaded from YouTube);add POS tags to a given text or closed caption file;segment a given text into sentences;segment a given text into closed captions (several algorithms are
available);train and use machine learning models to segment raw text into CC
lines.InstallationDO NOT USE THIS PACKAGE IN PRODUCTION UNTIL IT REACHES v1.0.0 !!!pipinstalllachesisInstalling dependenciesYou might need additional packages, depending on how you plan to uselachesis:lxml >= 3.6.0for reading or downloading TTML files;youtube-dl>= 2017.1.16for downloading TTML files;python-crfsuite>= 0.9.1for training and using CRF-based
splitters.By design choice, none of the above dependencies is installed bypip install lachesis. If you want to install them all, you can use:pipinstalllachesis[full]Alternatively, manually install only the dependencies you need. (You can
do it before or after installinglachesis, the order does not
matter.)Installing NLP LibrariesIn addition to the dependencies listed above, to perform POS tagging and
sentence segmentationlachesiscan use one or more of the following
libraries:Pattern(install withpip install pattern,see
here)NLTK(install withpip install nltk,see
here)spaCy(install withpip install spacy,see
here)UDPipe(install withpip install ufal.udpipe,see
here)If you want to install them all, you can use:pipinstalllachesis[nlp]or[fullnlp]if you also want[full]as above.Each NLP library also needs language models which you need to
download/install separately. Consult the documentation of your NLP
library for details.lachesisexpects the following directories in your home directory
(you can symlink them, if you installed each NLP library in a different
place):~/lachesis_data/nltk_dataforNLTK(see
here);~/lachesis_data/spacy_dataforspaCy(see
here);~/lachesis_data/udpipe_dataforUDPipe(see
here).The NLP libraryPatterndoes not need a separate download of its
language models, as they are bundled in the file you download when
installing throughpip install pattern.The following table summarizes the languages supported by each library
in their standard language models pack. (Additional languages might be
supported by third party projects/downloads or added over time.)Language / LibraryPatternNLTKspaCyUDPipeArabic✓Basque✓Bulgarian✓Croatian✓Czech✓✓Danish✓✓Dutch✓✓✓English✓✓✓✓Estonian✓✓Finnish✓✓French✓✓✓German✓✓✓✓Gothic✓Greek✓✓Greek (ancient)✓Hebrew✓Hindi✓Hungarian✓Indonesian✓Irish✓Italian✓✓✓Latin✓Norwegian✓✓Old Church Slavonic✓Persian✓Polish✓✓Portuguese✓✓Romanian✓Slovenian✓✓Spanish✓✓✓Swedish✓✓Tamil✓Turkish✓UsageDownload closed captions from YouTubefromlachesis.downloadersimportDownloaderfromlachesis.languageimportLanguage# set URL of the video and language of the CCsurl=u"http://www.youtube.com/watch?v=NSL_xx2Qnyc"language=Language.ENGLISH# download automatic CC, do not save to fileoptions={"auto":True}doc=Downloader.download_closed_captions(url,language,options)print(doc)# download manually-edited CC, saving the raw TTML file to diskoptions={"auto":False,"output_file_path":"/tmp/ccs.ttml"}doc=Downloader.download_closed_captions(url,language,options)print(doc)Parse an existing TTML file downloaded from YouTubefromlachesis.downloadersimportDownloader# parse a given TTML file downloaded from YouTubeifp="/tmp/ccs.ttml"doc=Downloader.read_closed_captions(ifp,options={u"downloader":u"youtube"})print(doc.language)# print several representations of the CCsprint(doc.raw_string)# multi line string, similar to SRT but w/o ids or timesprint(doc.raw_flat_clean_string)# single line string, w/o CC line marksprint(doc.raw.string(flat=True,eol=u"|"))# single line string, CC lines separated by '|' charactersTokenize, split sentences, and POS taggingfromlachesis.elementsimportDocumentfromlachesis.languageimportLanguagefromlachesis.nlpwrappersimportNLPEngine# work on this Unicode strings=u"Hello, World. This is a second sentence, with a comma too! And a third sentence."# but you can also pass a list with pre-split sentences# s = [u"Hello World.", u"This is a second sentence.", u"Third one, bla bla"]# create a Text object from the Unicode stringdoc=Document(raw=s,language=Language.ENGLISH)# tokenize, split sentences, and POS tagging# the best available NLP library will be chosennlp1=NLPEngine()nlp1.analyze(doc)# the text has been divided into tokens, grouped in sentencesforsindoc.sentences:print(s)# rawprint(s.string(tagged=True))# taggedprint(s.string(raw=True,eol=u"|",eos=u""))# raw w/o CC line and sentence marks# explicitly specify the NLP library NLTK,# other options include: "pattern", "spacy", "udpipe"nlp2=NLPEngine()nlp2.analyze(doc,wrapper=u"nltk")...# if you need to analyze many documents,# preload (and keep in cache) an NLP library,# even different ones for different languagesnlp3=NLPEngine(preload=[(u"en",u"spacy"),(u"de",u"nltk"),(u"it",u"pattern"),(u"fr",u"udpipe")])nlp3.analyze(doc)...Split into closed captionsfromlachesis.elementsimportDocumentfromlachesis.languageimportLanguagefromlachesis.nlpwrappersimportNLPEnginefromlachesis.splittersimportCRFSplitterfromlachesis.splittersimportGreedySplitter# create a document from a raw strings=u"Hello, World. This is a second sentence, with a comma too! And a third sentence."doc=Document(raw=s,language=Language.ENGLISH)# analyze it using the NLP library Patternnlpe=NLPEngine()nlpe.analyze(doc,wrapper=u"pattern")# feed the document into the CRF splitter (max 42 chars/line, max 2 lines/cc)spl=CRFSplitter(doc.language,42,2)spl.split(doc)# print the segmented CCsforccindoc.ccs:forlineincc.elements:print(line)print(u"")# the default location for CRF model files is ~/lachesis_data/crf_data/# but you can also specify a different pathspl=CRFSplitter(doc.language,42,2,model_file_path="/tmp/yourmodel.crfsuite")spl.split(doc)# if you do not have pycrfsuite installed# or the CRF model file for the document language,# you can use the GreedySplittergs=GreedySplitter(doc.language,42,2)gs.split(doc)Train a CRF model to segment raw text into CC lines$# /tmp/ccs/train contains several TTML files to learn from$# you can download them from YouTube using lachesis (see above)$ls/tmp/ccs/train0001.ttml0002.ttml...$# extract features and labels from them:$python-mlachesis.ml.crfdumpeng/tmp/ccs/train//tmp/ccs/train.pickle...$# train the CRF model:$python-mlachesis.ml.crftraineng/tmp/ccs/train.pickle/tmp/ccs/model.crfsuite...$# evaluate the model on the training set$python-mlachesis.ml.crftesteng/tmp/ccs/train.pickle/tmp/ccs/model.crfsuite...$# you might want to evaluate on a test set, disjoint from the training set,$# that is, the test set contains CCs not seen during the training:$ls/tmp/css/test1001.ttml1002.ttml...$python-mlachesis.ml.crfdumpeng/tmp/ccs/test//tmp/ccs/test.pickle$python-mlachesis.ml.crftesteng/tmp/ccs/test.pickle/tmp/ccs/model.crfsuite...$# now you can build a CRFSplitter$# with model_file_path="/tmp/ccs/model.crfsuite" as shown aboveTODO: decide and document where pre-trained model files can be
downloadedLicenselachesisis released under the terms of the GNU Affero General
Public License Version 3. See theLICENSEfile for
details.